Subscribe to Events
Overview
In order to receive web hooks, you must create one or more subscriptions. Subscriptions define what event types the tenant would like to receive web hooks for, the URI they wish to receive them on, and the type of security required by that URI.
Create a new Subscription
Sample Request
{
"uri": "https://the.uri-of-my.site/where/I/want/the/hook",
"secret": "there-is-always-room-for-jello",
"security": {
"type": "apiKey",
"apiKey": "my-api-key"
},
"eventTypes": [ "alert.sent", "namedIncident.created", "namedIncident.updated" ],
"isActive": true
}
Testing a Subscription
Once a subscription has been created, it can be tested by making a GET request to /v2/settings/subscriptions/{id}/test. This will result in a small request containing only the string "Ping!" being sent to the URI configured in the subscription. This can be useful for testing security configurations to ensure that web hooks will successfully reach the client endpoint.
Subscription History
Web hook request and response pairs are logged alongside timestamps and other metadata. This data can be requested at GET /v2/settings/subscriptions/{id}/history. This can be especially useful during setup of a new subscription when coupled with the testing endpoint.
Retry
Due to the nature of the web, it is presumed that occasionally a request to a client will fail. To combat this inevitability we have implemented a retry policy. If a web hook request is sent and we receive anything other than a 2xx response, we will retry the request up to 20 times with an increase of 2 ^ number of attempts in delay on each request up to a maximum delay of 1 hour between requests.