Webhook Guides

Webhook Retry Handling

Webhook retry handling decides what happens after a delivery fails. A provider may retry the original request, a webhook gateway may retry a stored event, or an operator may replay a failed window after a receiver is fixed. Without a clear model, recovery can create duplicate side effects or overload the same service that was already failing.

FastHook separates provider ingress from destination delivery. That means you can accept the provider request, inspect destination attempts, fix the receiver, and retry the failed branch without asking the provider to send every event again.

Webhook replay decision map for request replay, event retry, and bulk recovery.
Separate provider retry, request replay, and event retry. Each path has a different blast radius and a different idempotency requirement.

Retry paths

PathWho sends itUse whenRisk
Provider retryStripe, GitHub, Okta, Shopify, etc.Ingress endpoint failed before capture.Duplicate original request.
Request replayFastHookRouting rules changed and the original request should run again.May create new destination events.
Event retryFastHookOne destination branch failed after routing.Receiver must be idempotent.
Bulk replayOperator or automationA failed window needs recovery after an outage.Can overload a fragile receiver.

What to retry

  • Retry timeouts, network errors, temporary 5xx responses, and rate-limit responses after backoff.
  • Pause or throttle the destination before replaying a large failed window.
  • Do not blindly retry authentication failures, validation errors, or malformed payloads.
  • Inspect the response body and attempt history before converting a one-event retry into bulk replay.
  • Make receivers idempotent before enabling automatic retry or operator replay.

Retry a failed FastHook event

Retry failed event
curl -X POST "https://api.fasthook.io/v1/events/evt_01JYFAILED/retry" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_3b5335b627084a838b"

Recovery checklist

  1. Confirm the provider request was captured.
  2. Identify whether routing, transformation, authentication, timeout, or receiver code caused the failure.
  3. Fix the destination and confirm it can handle one replayed event.
  4. Retry one failed event and inspect the new attempt.
  5. Filter the failed window narrowly before bulk replay.
  6. Watch delivery rate, success rate, and duplicate side-effect logs during recovery.

Related guides