Skip to main content

​
Retries & Delivery

​
What counts as success

A delivery succeeds when your endpoint returns any 2xx status (return 200). Anything else — 3xx, 4xx, 5xx, a connection failure, or a timeout — is a failure and will be retried.
Returning 2xx only means “received”. Do not use the response body to signal business outcomes; VitaRelay ignores it.

​
Retry behavior

Failed deliveries are retried with exponential backoff across a capped number of attempts. Each retry waits progressively longer than the previous one. After the final attempt fails, the delivery is dead-lettered and no further attempts are made. Retries reuse the same X-VitaRelay-Delivery id and the same payload, so a successful retry after a partial failure must not double-apply work on your side.

​
Building a reliable endpoint

1

Verify, then acknowledge

Check the signature, persist the raw event, return 200.
2

Process asynchronously

Push to a queue or background job. Slow inline work causes timeouts, and a timeout is a failed attempt.
3

Be idempotent

Store processed X-VitaRelay-Delivery ids and short-circuit duplicates.
4

Monitor

Alert on your own 5xx rate for the webhook route, and ask your VitaRelay admin to check the last-delivery status shown in the dashboard Webhooks panel when you suspect gaps.

​
Recovering from a dead-letter

If deliveries were dead-lettered while your endpoint was down, reconcile with the read API rather than waiting for a replay:
Then fetch anything that looks stale:
Webhooks are a notification channel, not the system of record. The API is always authoritative for current order state.