Delivery and retries
How delivery attempts are made, when they are retried, how backoff is calculated, and what your handler must guarantee.
These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.
How is a delivery attempted?
After receipt, the event is queued. A worker takes it, POSTs the stored body and headers to your destination, and records the outcome: status code, response time, and a response body excerpt. Anything in the 2xx range counts as delivered. Everything else is a failure.
Which failures are retried?
- A non 2xx status code.
- A connection failure, DNS failure, or TLS failure.
- A timeout. The default request timeout is 15 seconds.
A 410 response is treated as permanent and is not retried, because the destination is telling you the resource is gone.
What does the backoff look like?
The default policy is 5 attempts over roughly 15 minutes:
| Attempt | Delay before it runs |
|---|---|
| 1 | Immediate |
| 2 | 8 seconds |
| 3 | 32 seconds |
| 4 | 2 minutes |
| 5 | 12 minutes |
On Starter and above you can change attempt count and the backoff curve per endpoint. A common production setting is 8 attempts tapering over 6 hours, which survives a long deploy without hammering a destination that is already struggling.
Delays carry jitter, so a burst of events that fail together does not retry in lockstep.
What happens after the last attempt?
The event moves to the dead letter queue. It stays inspectable and replayable for the rest of your retention window, and it counts as failed in alerts and in the event log. Nothing is discarded. See replay.
Is delivery ordered?
No. Events are delivered as workers pick them up, and a retried event lands after events that succeeded on their first attempt. If order matters to your handler, order by a field in the payload rather than by arrival.
Is delivery exactly once?
No. Delivery is at least once. A destination that returns 200 after your side already committed, but where the response is lost in transit, is indistinguishable from a failure, so the event is retried. Use the event id as an idempotency key.
How fast is the first attempt?
A healthy first attempt normally leaves within a second of receipt. Queue depth during a spike can add to that, and the status page carries the current numbers.
What headers does my destination receive?
The provider’s original headers, plus ShellOrbit headers describing the delivery:
ShellOrbit-Event-Id: evt_9c41f0
ShellOrbit-Endpoint-Id: ep_7f3a91
ShellOrbit-Attempt: 3
ShellOrbit-Received-At: 2026-09-03T12:04:01.412Z
ShellOrbit-Signature: t=1788445441,v1=5f2b...
The signature header is described in signature verification.