Best practices

​

Handle out of order delivery

We make a best-effort attempt to deliver webhooks in the order they are generated. Your webhook handler should be resilient to events arriving out of order. For example, it is possible for your system to receive a PRODUCT_DELETED webhook before a PRODUCT_UPDATED webhook.

The createdAt field of each webhook can be used to determine whether the webhook you’ve received is old. For instance, you could track the greatest createdAt value you’ve observed for each product, and then use that to skip processing the earlier PRODUCT_UPDATED event.

The most reliable way to ensure you have the most up-to-date data is to fetch it from our API. In the case of product webhooks, this would mean calling productByID instead of relying on the product data inside the webhook payload.

​

Ignore duplicate webhooks

Rye’s systems attempt to deliver webhooks only once to your endpoint, but in some cases we might end up delivering the same webhook more than once.

Every webhook we send has a unique id field which can be used to detect duplicates. We recommend the following strategy:

1. Obtain the webhook id at the beginning of your webhook handler.
2. Check whether you have already processed a webhook with this id. You will need persistent storage for this (e.g. you could store all webhooks inside a SQL table, or store all webhook IDs within a key-value store like Redis).
3. If you have already processed this webhook id, then bail out of the webhook handler.
4. Otherwise, handle the webhook and store its id.

​

Implement reconciliation jobs

Sometimes webhooks get dropped during delivery due to network issues or your system being offline. In order to “catch up”, we recommend running a scheduled reconciliation job to periodically fetch fresh data from our systems.

For example you might generally rely on product webhooks to maintain your own local copy of product data, and then have a job which calls productByID for each product you’re tracking every day at noon to ensure you haven’t missed anything.

​

Process webhooks asynchronously

Our systems time out webhook deliveries that take longer than 10 seconds. If your webhook handler takes too long to process a webhook, then we will mark it as failed on our side and reattempt delivery later which will cause unnecessary additional load on your systems.

We recommend that your handler verifies the webhook’s authenticity and then queues the webhook for processing in the background, so that your endpoint can return a response to our system quickly.