Webhook Guides

How to Debug a Failed Webhook

A failed webhook is easier to debug when you do not treat it as one opaque failure. The provider request may have failed before ingress, been rejected by source auth, missed a route, failed at the destination, or been processed by the receiver but not by downstream business logic.

FastHook separates those stages into requests, events, attempts, retries, and replay. That gives you a practical debugging path before you ask a provider to resend payloads or start copying JSON from scattered logs.

Debugging order

  1. Confirm the provider delivery reached the FastHook source URL.
  2. Check whether the request was accepted or rejected at source auth.
  3. Inspect headers, path, query params, and payload shape.
  4. Confirm a connection matched and created a destination event.
  5. Read the destination attempt status, latency, and response body.
  6. Fix the receiver, retry one event, then replay a narrow window if needed.

Failure map

SymptomLikely layerNext check
Provider shows connection errorIngressSource URL, DNS, method, provider dashboard.
FastHook rejected requestSource authSignature secret, timestamp, method, token, raw body.
No destination attemptRoutingConnection filters, disabled connection, destination id.
Attempt 401 or 403Destination authCustom header, OAuth token, FastHook signature code.
Attempt 500 or timeoutReceiverService health, slow work, retry policy, idempotency.

Inspect failed events

List failed events
curl "https://api.fasthook.io/v1/events?source_id=src_q6z62b6py5o79b&status=FAILED&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_3b5335b627084a838b"

Retry after the fix

Retry only after the root cause is fixed. A retry before a bad secret, bad route, or broken receiver is corrected just creates another failed attempt.

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

Common mistakes

  • Verifying signatures after parsing and re-stringifying JSON.
  • Changing provider URLs during an incident instead of fixing the destination behind a stable source.
  • Replaying a broad time window before testing one event.
  • Ignoring receiver idempotency because the retry is initiated by an operator.
  • Treating a provider 2xx as proof that every downstream side effect succeeded.

Incident notes to capture

Good debugging leaves a trail that the next incident can reuse. Capture the provider delivery id, FastHook request id, event id, destination id, attempt status, response body, and the exact fix that changed the outcome.

If the webhook affected money, account access, inventory, or customer communication, write down whether a replay was performed and which idempotency key prevented duplicate side effects.

  • Provider delivery id or event id.
  • FastHook request, event, and attempt ids.
  • Receiver response status and response body.
  • Whether the failure was ingress, routing, destination, or receiver processing.
  • The smallest time window that was retried or replayed.

Related guides