Integration API

To send a Signal to AlertGrid, you need to send an HTTP request to http://hq.alert-grid.com/save-signal/ (both POST and GET methods are allowed). Two mandatory parameters are required:

  • api_id – this value authenticates the sender (you). Find your api_id in the Administration->Account Settings page.
  • receiver_name – name of the Receiver. Receivers can be added in the Receivers tab by clicking the “Add new Receiver” button.

After sending the request AlertGrid will return a simple, plain text response. It can be in one of the two following formats:

OK:[number], e.g. "OK:563"

or

ERROR:[number], e.g. "ERROR:11"

OK means that the signal was accepted and saved correctly. The returned number is the ID of the saved signal.

ERROR means that saving the signal failed. Error codes are explained below.

Apart from the api_id and receiver_name, you can pass any number of other parameters; the only thing to remember is to always url-encode the parameter values. You can then use submitted parameters in Workflows. For instance, if you pass the free_disk_space value (integer) in a Signal, you’ll be able to create a Workflow which will send an email or SMS message to you when the free_disk_space value drops below 10.

The following table presents codes that can be returned by AlertGrid, together with their meanings.

Code Description
0 Unknown error. Please notify AlertGrid support (support@alertgrid.com).
11 receiver_name was not passed in the Signal
12 api_id was not passed in the Signal
21 A Receiver with this name does not exist.
22 The Receiver is disabled and cannot receive Signals.
31 api_id is incorrect


Note: when you use the POST method to call save-signal and pass parameters in URL (query string), these parameters will be accepted and overwrite the params with the same name sent in the POST body. For instance, sending a POST request to http://alert-grid.com/save-signal/?api_id=1234&receiver_name=abc&foo=bar these will make alert-grid use these three passed params (api_id, receiver_name and foo) plus anything you sent as POST data.