Webhook Guides

Webhook Failure Recovery

Webhook failure recovery is the operational workflow after delivery breaks. The provider may have sent the event, your gateway may have accepted it, and one downstream destination may still have failed. Recovery is safest when each stage has evidence.

FastHook keeps the original request, routed event, destination attempt, response status, response body, and retry path together so teams can recover without copying payloads from logs.

Webhook failure recovery and replay safety runbook.
Recover in stages: inspect, fix, retry one event, then replay only the failed window with throughput and idempotency controls.

Recovery runbook

  1. Confirm the provider request arrived and was accepted.
  2. Find the routed event and destination branch that failed.
  3. Inspect response status, response body, latency, and retry count.
  4. Fix the destination code, credentials, network route, or payload mapping.
  5. Retry one failed event and inspect the new attempt.
  6. Replay a filtered window only after the receiver handles duplicates safely.

Failure types and recovery action

FailureLikely causeRecovery
401 or 403Destination auth or secret mismatch.Fix credentials before retry.
404 or 405Wrong endpoint path or method.Update destination URL or method.
429Receiver is rate limited.Throttle replay and retry later.
Timeout or 5xxTemporary outage or slow receiver.Retry one event after service health recovers.

Retry one event first

Retry one 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"

Do not replay blindly

Bulk replay is powerful, but it can also turn a small outage into a second incident. Filter by source, destination, status, and time range. Use destination rate limits when the receiver has limited capacity.

Related guides