Webhook Guides
Webhook Retries
Webhook retries protect delivery when a receiver is temporarily unavailable, slow, rate limited, or returning server errors. They do not replace idempotency, logging, or manual replay, but they reduce the number of incidents that require a human to resend events.
FastHook applies retry behavior at the delivery branch, records each attempt, and keeps response status, latency, and failure details available before a team decides whether to keep retrying or replay manually.
Why webhook delivery fails
- The destination is down during a deploy or incident.
- A downstream API returns 429 because a provider sent a burst of events.
- Credentials expired or a destination URL changed.
- The receiver rejects a payload after a schema or validation change.
- The endpoint responds too slowly for the delivery timeout.
Retry policy
A retry policy should define which failures are retryable, how long to wait between attempts, and when to stop. FastHook retry rules belong close to the connection so each delivery branch can match the receiver it protects.
| Signal | Typical policy | Reason |
|---|---|---|
| 429 | Retry with backoff and respect receiver capacity. | The destination is asking for slower traffic. |
| 500-599 | Retry automatically for a limited number of attempts. | Server-side errors are often temporary. |
| 401 or 403 | Do not keep retrying until credentials are fixed. | Authentication failures usually need operator action. |
| 400 or 422 | Inspect before retrying. | The payload or transformation may be invalid. |
Exponential backoff
Exponential backoff spaces retries apart so a struggling receiver has time to recover. It also prevents webhook retry storms where the retry system makes the outage worse.
- Use short delays for ordinary transient failures.
- Use longer delays for receivers that protect expensive APIs or databases.
- Set an upper attempt limit so permanent failures move to operator review.
- Pair backoff with destination rate limits when replaying old failures.
Automatic retry vs manual replay
| Mode | Best for | Needs operator review |
|---|---|---|
| Automatic retry | Temporary receiver errors and throttling. | When attempts keep failing. |
| Manual event replay | Known failures after a receiver or route fix. | Before replaying a wide window. |
| Request replay | Running the original request through current routing again. | When filters or transformations changed. |
Duplicate delivery is part of reliable delivery
A reliable webhook system assumes duplicates can happen. Providers retry, FastHook retries, and operators may replay events after a receiver is fixed. The receiver should use provider delivery ids, event ids, or business object ids to make repeat delivery safe.
- Store idempotency keys before creating external side effects.
- Treat duplicate delivery as expected behavior, not an exceptional bug.
- Use delivery attempt logs to understand which retry created which receiver response.
- Only widen retry or replay windows after testing one event.
Retry logs
Retry logs should answer what happened on every attempt. FastHook stores destination URL, method, response status, response body preview, latency, trigger, and attempt number so engineers can distinguish a bad receiver from a bad route.
- Search failed events by source, connection, destination, status, and time window.
- Inspect latest attempts before editing retry rules.
- Use response bodies to identify auth, validation, timeout, or rate limit failures.
- Keep retry history attached to the event that may later be replayed.
Webhook retries FAQ
Should webhook retries be automatic?
Retry transient 429 and 5xx failures automatically, but route permanent auth or validation errors to human review.
Can retries create duplicate events?
Yes. Receivers should be idempotent because providers, FastHook, and operators can all produce repeat deliveries.
When should I use replay instead of retry?
Use replay after the underlying issue is fixed and you want to recover a known event or request window.