Webhook Delivery

When a NextZen webhook is delivered to your registeded webhook receiver endpoint, your receiver should do the following:

Your system acknowledges that it received webhooks by sending NextZen a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook. NextZen will consider these codes to be an error response.

Because NextZen has a connection timeout of five second, the your server must accept connections within five seconds.

NextZen's webhook delivery system uses HTTP Keep-Alive to reuse connections to the same host and endpoint. This reduces network congestion and the latency in subsequent requests. Ensure that you have Keep-Alive enabled for your endpoint to reduce the overhead of receiving concurrent requests.

In instances where you can't provide a response in less than five seconds, NextZen recommends queuing your webhooks. Your queue should be persistent. Common practice here is also to build a reconciliation job that retrieves the data that is important for you, and you might have missed, periodically using our APIs.

NextZen waits five seconds for a response to each request to a webhook. If there's no response, or an error is returned, then NextZen retries the connection 20 times over the next 48 hours. If there are 20 consecutive failures, then the webhook subscription is automatically suspended and the organization owner is notified by email. Once you have corrected the problem with your webhook receiver, you can re-enable your subscription using the Developers page of your NextZen organization app.

Warning emails that the subscription is failing, and could be deleted, are sent to the organization owner's email address. This is the email address that was used to create your user account.

You can learn more about troubleshooting your webhooks in the Troubleshoot your webhooks guide here.

Before you respond to a webhook, you need to verify that the webhook was sent from NextZen. You can verify the webhook by calculating a digital signature.

Each webhook includes a base64-encoded X-NextZen-Hmac-SHA256 header, which is generated using the your client secret along with the data sent in the request.

The client secret can be downloaded when creating an OAuth Client from the Developers page of your NextZen organization app.

Compute the HMAC digest according to the following algorithm. This code snippet is specific to NodeJS and express.

Raw Body Parsing: NextZen's HMAC is based on the raw request body. If you're using a body parser middleware like express.json(), it will parse the body before your webhook verification code gets to it. You need to capture the raw body before it's parsed or you can minify the parsed JSON body with JSON.stringify.

Middleware Order: Ensure that your webhook verification middleware is placed before any body parsing middleware in your app.

Encoding: Ensure your encoding is set properly.

Queuing is a useful pattern to also handle occasional bursts of traffic. To queue, you can install a package like Better Que (or similar for the programming language of your choice) to store the webhook payload in a message queue to process later.

Queuing reduces the chance of the request timing out and having the webhook delivery count as a failure. This should enable your app to respond quickly, and for your job to take as long as it needs to complete, ensuring that your system is resilient to a high volume of requests.