Webhook Guides

Webhook Failed Delivery

A webhook failed delivery means a destination did not successfully accept a routed event. The original provider request may still have been captured correctly, so recovery should focus on the failing branch instead of blindly asking the provider to resend everything.

FastHook keeps the accepted request, routed event, destination attempt, response status, response body, retry count, and replay path together. That makes failed delivery recovery a controlled workflow rather than a log search.

What failed delivery means

LayerRecordRecovery action
Provider ingressRequestFix source URL, auth, or method if the request was rejected.
RoutingEventFix filters or connection state if no destination event was created.
DestinationAttemptFix receiver URL, auth, rate limit, schema, timeout, or service health.
RecoveryRetry or replayRetry one event, then replay a filtered window only if safe.

Status code guide

  • 400 often means schema, validation, or payload shape mismatch.
  • 401 or 403 usually means destination auth is wrong or expired.
  • 404 or 405 usually means the destination URL path or method is wrong.
  • 429 means the receiver needs slower delivery or a later retry.
  • 500-599 and timeouts are usually retryable after the receiver is healthy.

Inspect attempts

Read attempts for one event
curl "https://api.fasthook.io/v1/attempts?event_id=evt_01JYFAILED&order_by=created_at&dir=desc&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_3b5335b627084a838b"

Recovery runbook

  1. Read the latest attempt response status and body.
  2. Fix the receiver, credentials, route, payload mapping, or rate limit.
  3. Confirm receiver idempotency for the affected event type.
  4. Retry one failed event and inspect the new attempt.
  5. Replay a narrow failed window if the one-event retry succeeds.

Avoid a second incident

Bulk replay can overload the same destination that failed earlier. Pause unrelated connections, set a destination rate limit, and replay by source, destination, status, and time range instead of redelivering every stored request.

Provider failure vs destination failure

The recovery path depends on where the failure happened. If the provider never got a successful response from the source URL, the provider may retry the original request. If FastHook accepted the request and only the destination failed, the safer recovery path is usually a FastHook event retry.

Keeping those two paths separate prevents duplicate recovery. You do not want the provider to resend a broad window while an operator also replays the same captured events through the gateway.

  • Use provider retry when the ingress request was never accepted.
  • Use event retry when one destination branch failed after capture.
  • Use request replay when routing or transformations changed after capture.
  • Use bulk replay only after one-event recovery proves the receiver is safe.

Related guides