Best Practices for Webhooks

Review these best practices to help keep your webhooks secure and function seamlessly with your integration. To find out more about setting up and receiving webhooks, visit the Webhooks guide.

Webhook security

There are a few measures that can be taken to ensure webhooks are secure. Only HTTPS URLs are supported and require a valid SSL certificate. Self-signed certificates are not supported.
Below are some additional security-related methods:

Method

Description

IP whitelisting

Whitelist the following IPs that webhooks will be sent from, noting the different environments:

Pre-live
54.183.18.207
54.183.142.227
13.237.240.238
54.66.162.247
52.63.199.160

Production
54.183.18.207
54.183.142.227
3.24.122.159
54.79.20.55
52.62.134.160

URL obfuscation

When creating a webhooks POST endpoint, use an obfuscated URL to ensure it cannot be easily accessed by an insecure source.
For example: https://example.com/webhooks/items/1bb77e2f892ebab9b2

Secondary API call

Using the ID provided within the webhook, you can initiate another API call to fetch the resource from Zai once again. This ensures the request and response occur between both backends. Example: A webhook of GET /items/:id reaches the endpoint. In the payload, there is an ID. Using the ID, make a call to GET /items/:id to ensure the data is coming from the Zai API.

Verify events are sent from Zai

Verify webhook signatures to ensure that events received are sent from Zai.

Retry feature

Webhook jobs will be automatically retried in case they fail to be delivered. Our application will automatically re-attempt to send webhook notifications to customers for up to 24 hours with an exponential backoff capability.

Retry attempts

Estimated retry timings

1

5 minutes

2

25 minutes

3

1 hour & 45 minutes

4

7 hours & 5 minutes

5

28 hours & 25 minutes

📘

Note

In the event that the maximum number of automatic retry attempts is exhausted, we’ve maintained the ability for our internal team members to manually resend failed webhook notifications.
In the future, we will expose features to allow enhanced searching of webhooks and the ability to retrigger a failed webhook via an API.

Testing

There are a number of ways to start testing Webhooks with Zai. We recommend services such as Request Bin, Runscope and/or Webhooks.site, all of which can be used to provide a container for all webhooks to be sent to.


Did this page help you?