Webhook

A WebHook is a simple event-notification via HTTP POST. This service sends the alert payload to a URL that you specify any time the alert is triggered.

Webhook Configuration

Navigate to the “Notification Services” section of your Organization page. Click on the Webhook integration, then on the “Add Configuration” button.

outbound_webhook_config

Enter a name for the service webhook in the Title field. In the URL field, enter a URL address that will receive a POST request anytime an alert is fired with this service.

Creating Alerts

After setting up the service you can tie alerts to a service destination. You can read more about creating alerts in the Alerts knowledge base article.

POST request

When an alert is fired that uses the webhook service a POST request will be made to the URL provided. The POST request will be in the format used by the github-services suite of webhook handlers. The POST body will contain a single parameter called payload, which will contain a JSON hash.

Example Payloads

The following is an example payload sent to the POST address when the webhook is triggered:

{
   "alert": {
      "id": 5846005,
      "name": "collectd.high.load",
      "runbook_url": "http://example.com/runbook.pdf",
      "version": 2
   },
   "incident_key": "<key that uniquely identifies this alert incident>",
   "account": "m@example.com",
   "trigger_time": 1444177459,
   "conditions": [
      {
         "id": 1150670,
         "type": "above",
         "threshold": 2,
         "duration": 300
      }
   ],
   "violations": {
      "example-ubuntu-14.04": [
         {
            "metric": "collectd.load.load.shortterm",
            "value": 7.190000057220459,
            "recorded_at": 1444177454,
            "condition_violated": 1150670,
            "count": 31,
            "begin": 1444177140,
            "end": 1444177440
         }
      ]
   }
}

Example payload for a Cleared Alert:

{
  "payload": {
    "alert": {
       "id": 6268092,
       "name": "a.test.name",
       "runbook_url": "",
       "version": 2
    },
    "incident_key": "<key that uniquely identifies this alert incident>",
    "account": "youremail@yourdomain.com",
    "trigger_time": 1457040045,
    "clear": "normal"
  }
}

Note

The trigger_time in this payload is the timestamp when the alert cleared, not when the alert originally fired.

Encoding

The payload JSON hash is encoded with application/x-www-form-urlencoded, as is standard for all POST requests. Apps rarely need to consider this because almost all Web frameworks automatically URL-decode the POST contents. In those cases, the app only needs to decode JSON.