Browse the docs
Webhooks
Retries & delivery
How Inboundr retries failed webhook deliveries: what counts as a failure, the backoff schedule, delivery statuses and handler best practices.
Inboundr retries failed deliveries automatically, so a short outage on your side doesn't lose mail.
What counts as a failure#
A delivery attempt fails if the endpoint:
- returns a non-
2xxstatus, - returns a
3xxredirect (redirects are not followed), - times out (10 seconds by default, configurable from 1 to 30), or
- can't be reached.
Backoff schedule#
Failed attempts are retried with increasing delays until one succeeds or the
endpoint's maxAttempts is reached (5 by default, up to 10):
| Attempt | Delay after previous |
|---|---|
| 1 | immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5+ | 2 hours |
After the final attempt, the delivery is marked dead and shown in the console, where you can inspect the response and retry it by hand.
Delivery status#
Each email's overall delivery status sums up its attempts:
| Status | Meaning |
|---|---|
delivered | At least one endpoint accepted it and none are failing. |
pending | Attempts are still in flight. |
failed | One or more deliveries failed or went dead. |
Writing a reliable handler#
Be idempotent
A delivery can arrive more than once, for example when a retry fires after
your handler succeeded but before its response reached Inboundr.
De-duplicate on the email id or the X-Inboundr-Delivery-Id header.
Acknowledge quickly
Return 200 as soon as you've stored the event, then do slow work in the
background. Long processing risks a timeout, which triggers a retry.
Verify before trusting
Always verify the signature before acting on a payload.