Webhook Guides

Webhook Retry Logic Explained

Webhook retry logic decides when a failed delivery should be attempted again. The hard part is not sending the request twice; it is doing that without duplicate side effects, retry storms, or confusing provider retries with gateway retries.

FastHook separates provider ingress from destination delivery. If the provider request was captured, FastHook can retry the failed destination event or replay stored requests after routing changes, while keeping attempt evidence visible.

Retry vs replay

TermTriggerUse when
Provider retryProvider sees non-2xx or timeoutThe provider could not confirm your ingress accepted the request.
FastHook event retryDestination event failedOne branch failed after FastHook already captured the request.
Request replayOperator intentionally reprocesses stored requestRouting changed or a failed window needs recovery.
Bulk replayOperator selects a time windowMany stored events need recovery after a fix.

What should be retried

  • Network errors, timeouts, 429 responses, and temporary 5xx responses.
  • Receiver outages after the service is healthy again.
  • OAuth token refresh failures after credentials are fixed.
  • Rate-limited destinations with a slower replay pace.

What should not be retried blindly

  • Invalid signatures or source auth failures.
  • Permanent 400 validation errors caused by bad schema or missing fields.
  • 401 or 403 destination auth failures before credentials are corrected.
  • Non-idempotent side effects without an event id or delivery id guard.

Retry rule example

Exponential retry rule
{
  "type": "retry",
  "strategy": "exponential",
  "count": 5,
  "interval": 60000,
  "response_status_codes": ["429", "500-599"]
}

Safe retry checklist

  1. Use an idempotency key before creating side effects.
  2. Capture the response body for each attempt.
  3. Back off retries so a failing receiver has time to recover.
  4. Retry one event before replaying a batch.
  5. Throttle replay when the destination has limited capacity.

Backoff design

Retry intervals should get slower as failures continue. Immediate tight-loop retries turn a temporary receiver outage into more load at exactly the wrong time. Exponential backoff gives the receiver room to recover while still making progress on transient failures.

The right count depends on the business impact of delay and the receiver's capacity. Billing and order events often deserve several retries with clear operator visibility; noisy analytics events may be better dropped or replayed manually after inspection.

  • Retry 429 and 5xx responses more readily than 400 validation failures.
  • Use destination rate limits before replaying a large backlog.
  • Keep manual replay visible in audit logs because it can create duplicate deliveries.
  • Document which event types are safe for automatic retry.

Related guides