Webhook Guides

Webhook Debugger

A webhook debugger should answer one question quickly: where did this delivery stop? Provider dashboards show only part of the story, and receiver logs usually start too late. FastHook keeps the inbound request, routed event, destination attempt, response body, retry state, and replay action in one trace.

Use FastHook as an online webhook debugger when you need to inspect headers, payloads, request paths, source authentication failures, filter misses, destination errors, timeout responses, duplicate retries, or replay behavior without building temporary logging endpoints inside every application.

A useful debugger keeps ingress and delivery evidence separate. First prove what arrived, then prove what was routed and delivered.

What a webhook debugger should show

QuestionFastHook recordFields to inspect
Did the provider reach us?Requeststatus, headers, body, path, query
Was the source accepted?Requestverified, rejection_cause, source auth result
Did a route match?Eventconnection_id, destination_id, ignored/filter state
What did the receiver return?Attemptresponse_status, body, requested_url, error_code
Is replay safe?Event and request historyattempt count, receiver fix, idempotency key, retry scope

Webhook debug online

Online debugging is useful when the provider is already sending real traffic or when a teammate needs a shared trace. Create a FastHook source URL, send a fixture or provider event, then inspect request, event, and attempt records without adding temporary logging code to the receiver.

Fast triage workflow

  1. Find the inbound request in a narrow time range.
  2. Open the request with include=data to inspect payload, headers, query, path, method, and rejection cause.
  3. If the request was accepted, inspect events created from that request.
  4. Open destination attempts for the failed event and read the response body before retrying.
  5. Fix source auth, filters, destination URL, receiver credentials, or receiver code.
  6. Retry one event first. Use request replay only when current routing should re-process the original request.

Turn a captured failure into a regression fixture

Once the failure is understood, preserve the exact request that exposed it. A named Saved Event keeps the captured request connected to its source evidence and gives the team a repeatable regression case for the receiver fix. This is more reliable than copying a payload into a scratch file and losing its context.

The request inspector is the handoff from incident evidence to a reusable test: name the edge case and record what should happen.
  1. Capture: reproduce the provider request or find the failed production delivery.
  2. Save fixture: preserve the request as a named Saved Event with the expected behavior.
  3. Choose destination: target the receiver or connection that contains the fix.
  4. Replay: run one fixture and compare the new event, attempt, response, and side effect.

Useful regression fixtures

  • Successful payment: proves the happy path still creates exactly one expected side effect.
  • Invalid signature: proves source verification rejects the request before it reaches a destination.
  • Duplicate event: proves the receiver remains idempotent when the same delivery id is replayed.
Saved Events closes the debugging loop: select one destination, run the preserved case, and inspect fresh delivery evidence without waiting for the provider.

Open Saved events in the FastHook dashboard to run captured fixtures against a selected destination.

Debug a webhook with cURL

Find rejected requests

Find rejected requests
curl "https://api.fasthook.io/v1/requests?source_id=src_q6z62b6py5o79b&status=rejected&from=now-1h&to=now&limit=20&include=data" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID"

Find failed routed events

Find failed events
curl "https://api.fasthook.io/v1/events?status=FAILED&from=now-1h&to=now&limit=20" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID"

Inspect attempts for one event

Inspect attempts
curl "https://api.fasthook.io/v1/attempts?event_id=evt_01jv8c4n9p3x7r2t6q5m1k0s8b&order_by=created_at&dir=desc&limit=20" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID"

Retry one failed event

Retry event
curl -X POST "https://api.fasthook.io/v1/events/evt_01jv8c4n9p3x7r2t6q5m1k0s8b/retry" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID"

Common debugger findings

  • No request: the provider is using the wrong URL, environment, or endpoint path.
  • Rejected request: method, source auth, provider signature, or source status stopped ingress.
  • Accepted request, no event: route filters or connection state prevented delivery.
  • Failed attempt: destination URL, credentials, payload contract, rate limit, timeout, or receiver code failed.
  • Repeated side effects: provider retry, FastHook retry, or operator replay found a non-idempotent receiver.

When to use request replay

Request replay runs the original accepted request through current routing. Use it when filters, connections, transformations, or destinations changed after the request arrived. If only one destination attempt failed, retry the existing event first so the blast radius stays small.

Replay with modifications

FastHook can also replay a captured request after editing the method, path, query string, headers, or body. Use modified replay to test a receiver fix, verify a new filter, remove a bad field, or send a smaller fixture through the same source and routing pipeline without waiting for the original provider to resend the event.

Replay with modifications
curl -X POST "https://api.fasthook.io/v1/requests/req_01jv8c3m7b2p4q9x6r5t1n0k8s/retry" \
  -H "Authorization: Bearer $FASTHOOK_API_KEY" \
  -H "x-team-id: $FASTHOOK_TEAM_ID" \
  -H "content-type: application/json" \
  --data '{
    "modifications": {
      "method": "POST",
      "path": "/debug/replay",
      "query": "dry_run=true",
      "headers": {
        "content-type": "application/json",
        "x-debug-replay": "true"
      },
      "body": "{\"event\":\"debug.fixture\",\"replay\":true}"
    }
  }'

Share sanitized request evidence

When the next person only needs to inspect one request, create a sanitized webhook request share. FastHook redacts authorization headers, cookies, API keys, provider signatures, tokens, passwords, and custom sensitive fields before returning an expiring public link for the request snapshot.

Related guides