Webhook retries
The retry schedule, the headers on a retried delivery, and what happens when retries run out.
A delivery is acknowledged when your endpoint returns any 2xx within 10 seconds. Anything else is retried.
Schedule
| Attempt | Delay since previous |
|---|---|
| 1 | immediate |
| 2 | 1 minute |
| 3 | 2 minutes |
| 4 | 4 minutes |
| 5 | 8 minutes |
| 6 | 16 minutes |
| 7 | 32 minutes |
| 8 onward | every hour |
Retries continue for 72 hours from the first attempt, then the delivery is marked exhausted and an alert is raised in your console. That is up to about 78 attempts.
Headers on a retry
| Header | Value |
|---|---|
Omi-Retry-Count | 1 for the first retry, 2 for the second, and so on. Absent on the first attempt. |
Omi-Retry-Reason | Why the previous attempt failed: timeout, http_<status> (e.g. http_503), or connect_failed. |
The body and the Omi-Event-Id are identical on every attempt. Omi-Signature-Timestamp and Omi-Signature are fresh on every attempt — each retry is signed with the current time, so your 5-minute timestamp window does not reject legitimate retries.
What triggers a retry
| Your response | Result |
|---|---|
2xx | Acknowledged. Done. |
3xx | Retried. OmiCloud does not follow redirects. Register the final URL. |
4xx, including 401 | Retried. |
5xx | Retried. |
| No response within 10 s | Retried, reason timeout. Your handler may still have run — deduplicate on id. |
| TLS or connection failure | Retried, reason connect_failed. |
When an endpoint keeps failing
Events are queued per endpoint. A failing endpoint does not block deliveries to your other endpoints, and it does not block newer events to itself — each event retries on its own schedule. A recovered endpoint will therefore receive a burst of backlog, possibly out of order. A receiver that fetches the transaction and acts on its current state handles this without special cases.
If an endpoint has had no successful delivery for 72 hours, OmiCloud marks it disabled and emails the operator's technical contact. Re-enable it with PATCH /v1/webhook-endpoints/{id} {"status":"active"} once it is fixed. Events that were exhausted while it was down are not re-sent automatically — replay them from the deliveries log in the console, or reconcile with GET /v1/transactions?since=….
Replaying
POST /v1/webhook-endpoints/{id}/deliveries/{eventId}/replay sends a specific event again, immediately, as a new attempt. Use it after fixing a bug in your receiver. Replays are signed fresh and carry Omi-Retry-Reason: manual_replay.
Updated about 2 months ago