Delivery and retries

What counts as delivered, how retries work and how to handle repeats.

Overview

A webhook is delivered when your server answers 2xx in time. Failed deliveries are tried again, so your server must cope with repeats.

Answer quickly

Any 2xx answer within 10 seconds counts as delivered. Anything else counts as a failure: another status, a timeout, or no connection. Redirects are not followed.

Tip Answer first and do the work afterwards. Put the event on a queue, answer 200, then process it.

Retries

A failed delivery is tried again up to 8 times, with longer waits between tries. Every try carries the same event ID.

After 30 failures in a row, O2M switches the address off and sends your company an alert. Events are not stored for an address that is off. Fix your server, then switch the address back on in Settings → API and Webhooks → Webhooks.

Handle repeats and order

An event can arrive more than once. Store each X-O2M-Delivery you have handled and ignore repeats.
Events can arrive out of order. A retried event can land after a newer one. Compare created_at, or read the current value from the API.
Do not rely on webhooks alone. Run a regular check with updated_since to catch anything missed while your server was down.

See and resend deliveries

The Deliveries list on the Webhooks page shows each event of the last 30 days with its result, tries and your server's answer. A failed one can be sent again with the same event ID.

Common problems

In the Deliveries list	Cause	What to do
The address answered 401	Your server refused the message, often over a signature check.	Check the signing secret and that you use the raw body.
The address answered 500	Your server failed while handling the event.	Check your server's logs.
No answer within 10 seconds	Your server took too long.	Answer first and do the work afterwards.
The address points inside a private network	The address leads to a private network.	Use a public address.
The webhook address is switched off	The address was off when the event was due.	Switch it back on.

Good to know Webhooks stop while the public API is switched off for your company, and start again when it is back on. Addresses are kept.