Build a webhook endpoint

This page walks you through the code that properly handles webhook notifications.

To make use of Allthings webhooks, you first need to build your own custom endpoint. A webhook endpoint is no different from any other server-side functionality you might implement. At its simplest, it is some server-side code which can receive POST requests.

Before building a webhook endpoint, there are several key considerations regardless of the technology involved. Please also review the best practices for using webhooks.

Key considerations

For each event occurrence, Allthings POSTs the webhook data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the JSON. Thus, at minimum, the webhook endpoint needs to expect data through a POST request and confirm successful receipt of that data.

When your endpoint receives an event, you must acknowledge receipt of the payload by returning a 2xx HTTP status code. All response codes outside this range, including 3xx codes, indicate to Allthings that you did not receive the event.

If your webhook endpoint does not return a 2xx HTTP status code, Allthings will attempt to deliver the event again. We will slowly back-off on attempted delivery until, after multiple failures to send the notification over multiple days, we mark the event as failed and stops trying to send it to your endpoint.

Because properly acknowledging receipt of the webhook notification is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic could cause a timeout.

Debugging delivery issues

As a developer, you can review all of the events Allthings attempted to deliver to your webhook endpoint using the Webhooks API

Performing the following GraphQL query on the Webhooks API will return a list of all attempted webhook deliveries, responses from your endpoint, and the respective HTTP status codes we received. Delivery history is kept for 30 days after which time it is irreversibly deleted.

Example code

A complete example of a webhook endpoint which implements all of the best practices is available on CodeSandbox here.

Edit Allthings Webhook Example

➡️ Next Step: Read about best practices