Device Down Callback URL

Usually when Alertra detects that your web site is down, you want a technical person on your staff to be notified via SMS, Instant Message (IM), or email. The staff person would then look at the type of error and attempt to resolve the problem and bring the server back up. But in some environments action can be taken automatically if the proper system can be notified of the problem. In addition, some customers may want an external record of an outage. The Callback URL feature can be used in both situations.

Setting a Callback URL

The Callback URL can be configured on the Device Setup screen in the Advanced Settings section. The URL will be called when the device is initially marked down. And will be called every time the device is marked down. The URL is not called on device up.

Important: The callback URL should not point to a resource located on the device being monitored. If the monitored device is down, the callback URL will fail too. Ideally the callback URL should not be on the same network since the device may be down because the network it is connected to is down.

The URL you supply will be called with parameters that the server can use to determine which device is down and what the problem is. All of the parameter names are prefixed with 'alertra_' so they won't conflict with any parameters you include in the callback URL.

Name Description
alertra_deviceid The unique internal ID of the device within the Alertra system. You can find this ID on theDevice Setup page near the bottom of the page.
alertra_name The Name field from the Device Setup page.
alertra_timestamp The UTC time the check that resulted in the device being marked down was started.
alertra_last_code The error code assigned by Alertra for this problem. Typical values are 3 (Protocol error) and 4 (error command called in script). 3 is sent for things like failure to make a TCP connection or HTTP 404 Not Found errors. 4 is sent when the 'error' command is called in a script. It can also be called when the Verify Text specified for the device cannot be found on the returned HTML page.
alertra_last_msg The high level error message associated with this server outage e.g. "Connection to HTTPS service failed".
alertra_last_proto_code For HTTP/S devices this is the status code returned by the webserver as part of the HTTP protocol. You can find a list of possible status codes here.
alertra_last_proto_msg The code description returned by the server. For instance, if the HTTP service returns a protocol code of 301, the message is typically "Moved Permanently".

Processing the Callback

This feature is designed to be open to development by you. The server processing the callback can do whatever is needed with the information. Here is some simple PHP code that takes the callback information and writes it to a log file.

callback.php


<?php

$fp = fopen( '/tmp/callback.txt', 'a' );
fwrite( $fp, $_REQUEST['alertra_name']
   . "," . $_REQUEST['alertra_deviceid'] 
   . "," . $_REQUEST[ 'alertra_last_code' ]
   . "," . $_REQUEST[ 'alertra_last_msg'] 
   . "," . $_REQUEST[ 'alertra_last_proto_code']
   . "," . $_REQUEST[ 'alertra_last_proto_msg']
   . "," . $_REQUEST[ 'alertra_timestamp']
   . "\n" );

?>

Summary

The callback URL function can be used to perform custom processing in response to a server outage. The URL is called on each device down event. You can configure a callback URL by setting the Callback URL field of the Device Setup page.