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.
Please note
In some cases, when a failed webhook is retried, it could be sent after a more recent update. For example, if an update happens in our system at 10:00am, and the webhook that's sent fails, then we attempt to send the same data again from the 10:00am update. If that retry attempt is sent at 10:05, there’s a chance that another update happened at 10:02am and it was successful. In this case, you’d have the latest data from 10:02am and you should discard any webhook data referring to the earlier update from 10:00am.
You can check a webhook payload’s
updated_atfield to determine whether the data is newer or older than the data that you currently have stored in your system.
For example, when receiving aUserswebhook payload, you could compare your own data against theusers.updated_atfield. Similarly, when receiving aBatch Transactionswebhook payload, you could compare your own data against thebatch_transactions.updated_atfield.
| 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.
Updated almost 2 years ago