Retries and replays
How PostShiba retries a failed webhook, when it gives up, and how to send it again.
When your endpoint doesn't return a 2xx, PostShiba retries the event on a fixed schedule. After the last attempt fails, the delivery is marked dead and you can replay it from the dashboard.
Retry schedule
Each event gets up to six attempts. The first is sent right away.
| Attempt | Sent after the previous failure |
|---|---|
| 1 | Immediately |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 8 hours |
| 6 | 24 hours |
Each wait is shortened by up to a fifth at random, so retries after a shared outage don't all arrive at once. Retries are picked up once a minute, so an attempt can land up to a minute after its scheduled time. If attempt 6 fails, the delivery is dead. That is about 30 to 35 hours after the first attempt.
A failure is any status outside 2xx, a redirect, a timeout, a refused connection, or a URL that resolves to a private address. Each attempt is signed again with a new X-Capsule-Timestamp.
Handle duplicates
Your server can receive the same event twice, for example when it handled the request but responded too late. Store sg_event_id and skip events you've already processed.
Replay dead deliveries
- Open Webhooks in the dashboard and select the endpoint.
- Check Recent deliveries for rows marked
deadand fix whatever was failing. - Click Replay dead letters.
Every dead delivery for that endpoint is queued again. A replayed delivery gets one more attempt. If that attempt fails, it goes straight back to dead.
The API has no replay action. Replays are dashboard only.
When an endpoint keeps failing
After 8 failed attempts in a row, the endpoint is Down. PostShiba stops sending to it and queues new events instead of dropping them.
While it is down, PostShiba retries one queued event at a time. The first retry comes within about a minute. Each later one waits about as long as the endpoint has been down, up to an hour, with some randomness. next_canary_at in the API says when the next one is due. A brief outage recovers in seconds, and an endpoint that stays down is contacted about once an hour.
The first success marks the endpoint Up and sends the queue in order. To resume right away after a fix, click Send test event. Changing the URL also resets the endpoint.
Queued events are kept for as long as PostShiba keeps events. An event tried while the endpoint is down uses one of its six attempts.
If you disable an endpoint, or remove an event type from it, pending retries for it are dropped.