Webhooks

Webhooks are developed to send events to your application(s) in real-time. You can see it as a reversed API: provide your endpoint and the platform makes sure you get the events you are interested in once they occur. The message coming from the webhook looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "sequenceNumber": 25618,
  "deliveryAttempt": 1,
  "eventId": "06811617-4836-48d1-a09b-42e624db9ekg",
  "eventTriggerId": "cb99d792-e994-4a18-bf75-5d39f09d7ekg",
  "eventTriggerVersion": 10,
  "eventLevel": "WARNING",
  "subjectId": "ad55bc6a-094c-4f6b-9cfe-871168cfeekg",
  "date": "2019-09-17T09:33:15.075+0000"
}

Configuring a webhook

The following general information is required for a webhook.

Event levels

Here you can select the event levels for which the webhook should be called. For example, you might only want to see Problem and Warning events being send to your external system.

Event triggers

Here you have some filter options to only have the webhook called for certain event triggers.

Subjects

Here you have some filter options to only have the webhook called for certain subjects.

Retry logic

In case a call fails (due to receiving a non-2xx response code or exceeding timeout of 5 seconds), we will try 4 more times: after 5 seconds, 1 minute, 5 minutes and 15 minutes. If it still fails for each of those attempts, it is counted as a non-successful delivery. To make this transparent to the receiving system all messages contain the field deliveryAttempt which can be used to monitor at which delivery attempt the call was received. If no retries were needed deliveryAttempt is equal to 1. Retrieving calls that failed, for example to reprocess them after a long period of downtime, can be done programmatically via our HTTP API.

Ordering guarantees

Date ordering is guaranteed for all events related to a specific event trigger and subject. We enforce that calls are made in the right order, however the order of receiving can differ due to network problems and the asynchronous nature of the platform. To make this transparent to the receiving system all messages contain an incrementing sequenceNumber which can be used to derive the order in which messages were sent.