Webhook Debugging for Engineers

Webhook bugs are often hard to reproduce. You usually see only a failed request, without full payload context and retry history.

A reliable debugging workflow reduces incident time and helps you fix provider-specific edge cases faster.

What is webhook debugging

It is the process of inspecting webhook request headers, payloads, delivery attempts, and downstream failures to identify why event handling broke.

How it works

  1. Capture every inbound request with headers and body.
  2. Inspect response code and error logs.
  3. Identify whether failure is signature, schema, or timeout.
  4. Fix handler and replay failed event.

Common problems

  • Missing raw payload needed for signature verification.
  • Unknown schema changes from provider.
  • No mapping between retries and original event.
  • Cannot replay real failed payloads safely.

How FastHook solves this

FastHook stores request history, surfaces failed attempts, and lets you replay specific events. This gives you real production payloads for debugging instead of synthetic guesses.

Code examples

Capture structured debug logs (Node.js)

app.post("/webhooks/provider", async (req, res) => {
  const event = req.body;
  const trace = {
    event_id: event.id,
    event_type: event.type,
    provider_request_id: req.headers["x-request-id"],
    received_at: new Date().toISOString()
  };

  console.log("webhook_trace", trace);
  res.status(200).send("ok");
});

Fetch failed requests (curl)

curl "https://api.fasthook.io/v1/requests?status=failed&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-team-id: team_123"

Failure record example

{
  "request_id": "req_9081",
  "event_id": "evt_123",
  "status": "failed",
  "response_status": 500,
  "error": "timeout after 15s"
}

Try FastHook

Inspect failed deliveries, replay events, and validate fixes before incidents repeat.