Debug production webhook failures locally

Guides / Workflow

A webhook failed in production. You have the error from your logs but not the request that caused it. Reproducing it means guessing at the payload, and you can't be sure your fix covers the real case.

HookWatcher already has the request. A Debug Session runs it against your local code as often as you need, records every attempt, and turns the final working attempt into a regression test.

The HookWatcher debugging loopCapture real webhook traffic, inspect it, replay it locally, debug, fix your code, save the event as a test, and run it in CI to prevent regressions.CaptureInspectReplayDebugFixTestPrevent regressionProduction webhook → reproduced on localhost → fixed → kept fixed in CI
The HookWatcher debugging loop

1. Find the failure

The Failures view lists failed forwarding deliveries, failed replays and failed tests across the workspace. Filter by endpoint, event type, provider, status code or time range. Each row opens the event or goes straight to Replay Locally, Modify & Replay, Debug or Save as Test. From the terminal: hwcli events list --forwarding failed.

2. Start a Debug Session

hwcli debug evt_93df18ab --forward http://localhost:8080/webhook

Attempt 1   500 Internal Server Error   188 ms
  TypeError: Cannot read properties of undefined (reading 'email')

[Enter] replay again  [e] edit  [s] save as test  [q] quit

Fix the code, press Enter, and the same request goes out again. Each attempt is listed with its status, response and time, in the terminal and on the event's Debug tab in the dashboard.

Attempt 2   500 Internal Server Error   102 ms
Attempt 3   200 OK                       44 ms   ✓ resolved

3. Find out what's different

If the cause isn't obvious, compare the failed event with a successful one of the same type: hwcli diff evt_93df18ab evt_19ac44e1. See Compare failed and successful webhooks.

4. Keep it fixed

Press s, or choose Save as Regression Test in the dashboard. The test stores the exact request and expects the response from your successful attempt. Run it in CI and the same bug can't come back unnoticed. See Run webhook tests in CI/CD.

Outside an interactive terminal, hwcli debug makes one attempt and exits 0 when your handler returns a 2xx status, so scripts can use it too.

Create an endpoint and capture your first webhook. No signup needed.

Start Free