Retries and idempotency

When Orbi retries a delivery

A delivery attempt is considered successful only when your endpoint responds with an HTTP 2xx status code.

Orbi retries a webhook delivery when any of the following occurs:

• Your endpoint returns a non-2xx status code
• The request times out
• The connection cannot be established (DNS, TLS, or other network errors)

Delivery timeout

Orbi uses a default request timeout of 10 seconds per delivery attempt.

If your endpoint does not respond within 10 seconds, the attempt is treated as failed and may be retried according to the retry schedule.

Recommendation
Acknowledge quickly with a 2xx response and move long-running work to a background job queue.

Retry schedule

Orbi uses an incremental backoff strategy with up to 21 total delivery attempts. Retries start quickly and then increase in delay, eventually retrying at longer intervals.

In practice, the schedule behaves like:

• An initial retry after ~30 seconds
• Followed by retries spaced a few minutes apart
• Then retries spaced 10–15 minutes apart
• Eventually continuing with ~30-minute intervals for later attempts

This approach balances fast recovery from short outages with sustained delivery attempts during longer incidents.

Idempotency

Each webhook delivery includes an idempotency key in the request headers:

• x-idempotency-key: <value>

If a webhook delivery is retried, Orbi re-sends the event with the same x-idempotency-key value. Your integration must treat this header as the primary deduplication key.

How to process events safely

A recommended workflow:

1. Read the x-idempotency-key header.
2. Check whether you have already processed this key.
3. If it has already been processed, return 2xx immediately.
4. If it has not been processed:
   • Persist the key atomically (or create a unique record keyed by it)
   • Process the event
   • Return 2xx

Important
Do not rely on timestamps, event types, or payload hashes for deduplication. Always use x-idempotency-key.

Best practices

• Return 2xx only after the event is safely accepted (for example, persisted or queued).
• Avoid long-running work in the webhook handler; enqueue background jobs and respond quickly.
• Log failures and monitor webhook delivery error rates.
• Design handlers to tolerate duplicates and out-of-order deliveries.