Receiving a Webhook Event

Webhook events should be processed as quickly as possible by the receiving system. Delays in processing the HTTP request can cause subsequent events to backup and, in extreme cases, cause events to be lost. Requests are made with a timeout of 15 seconds, so events must be consumed within that amount of time or the request will be considered a failure and will be retried. It is generally a best practice to consume webhook events asynchronously (i.e. submit the event to an internal queueing system and return quickly from the HTTP request) in order to isolate the sender from delays (and possible failures) due to actually processing the event.

Error Responses

In general, connection failures or error responses (any response code other than 2xx) will be retried for a limited number of times. As mentioned above, receivers should attempt to isolate event processing failures from receiving failures as much as possible using asynchronous processing if feasible. Some additional notes:

• 4xx - these error codes will be alerted more aggressively to the webhook owner because they typically indicate some sort of terminal failure which requires user intervention (e.g. something is not configured correctly)
• 410 - this error code is handled specially, and if received by guru, will automatically disable the webhook in question
• 5xx, general connection failures - in general, these are likely more transient failures and will not cause alerts unless enough failures accumulate to result in an undeliverable event

Example Webhook Event (SINGLE)

{
    "id":"64753163-9817-4500-9651-96177c32e3d1",
    "eventType":"card-created",
    "user":"[email protected]",
    "eventDate":"2021-04-13T13:53:00.000+0000"
}

Example Webhook Event (BATCH)

{
    "items": [
        {
            "data": {
                "channelId": "wh:b6109be3-9b86-4fb3-ae1a-5faa94b4fc97",
                "messages": [
                    {
                        "id": "0d765ec1-72c8-4443-970a-459faa3e5aa2:0",
                        "timestamp": 1620666399291,
                        "data": "{\"id\":\"64753163-9817-4500-9651-96177c32e3d1\",\"eventType\":\"card-created\",\"user\":\"[email protected]\",\"eventDate\":\"2021-04-13T13:53:00.000+0000\"}",
                        "name": "card-created"
                    }
                ]
            }
        }
    ]
}

Notes:

• the example is edited to remove some additional fields which are unimportant for consumers
• the values of the items and messages fields are both arrays which can contain more than one element
• the actual data value is a string value which must be parsed in order to be processed as JSON data