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 “Outbound” section of your Integrations page. Click on the Webhook integration, then on the “Add Configuration” button.

alert-services-webhook

Setup¶

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.

outbound_webhook_config

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 Introduction 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.