Skip to main content

Delivery and retries

Webhooks are delivered on a best-effort basis: Onebox retries failed deliveries, but it does not guarantee that every notification arrives, that it arrives only once, or that notifications arrive in order. Design your integration with that in mind: treat each webhook as a signal to fetch fresh data, make your processing idempotent, and reconcile periodically through the API.

Respond quickly with a 2xx​

A delivery succeeds when your endpoint answers with any 2xx status code within 10 seconds. The response body is ignored.

Acknowledge first and process later: verify the signature, store the notification or put it in a queue, answer 2xx, and do the slow work (calling the API, updating your systems) asynchronously. A response that arrives after 10 seconds counts as failed, even if your endpoint processed the request, and the notification will be delivered again.

Do not redirect

Configure the final URL of your endpoint, exactly as your server expects it. Redirects are not supported: a notification sent to a URL that redirects can be lost.

Retries​

Any other outcome counts as a failure: a non-2xx status code, a timeout or a connection error. Failed deliveries are retried up to 3 times within about a minute.

If the last attempt fails, the notification is discarded. It is not sent again later and cannot be requested again. If your endpoint is unavailable for longer than that, you miss the notifications sent in the meantime: see Reconcile with the API.

Handle duplicates​

The same notification can reach your endpoint more than once, for example when your endpoint processed a request but answered too late or with an error. Some changes also produce more than one notification: a refund can notify both the refund and the original order.

Make your processing idempotent:

  • Fetch, don't apply. Use the notification to fetch the current state of the order, event or session through the API and upsert it. Processing the same notification twice then gives the same result.
  • If you must deduplicate, use the content of the notification, such as ob-hook-id + ob-event + ob-action + code / item_id / id, within a short time window.

Ordering​

Notifications are not guaranteed to arrive in order, and they can arrive a few seconds after the change. Do not infer the state of an object from the sequence of notifications: always read it from the API.

Reconcile with the API​

Because a notification can be lost, do not use webhooks as your only source of truth for anything that must not be missed, such as accounting, access control or loyalty programs. Run a periodic reconciliation that asks the API for what changed since your last successful sync, for example purchases and refunds by time range in the Orders API. Webhooks then give you real-time updates and the reconciliation guarantees completeness.