How to debug incoming webhooks on your own machine
Webhooks are hard to debug because the request starts on someone else’s server. The trick is to capture one real delivery, then replay it locally as many times as you need.
Step 1: look at the sender’s delivery log
Before touching your code, open the dashboard of the service that sends the webhook. Most providers keep a list of recent deliveries with the status code your server returned, the time it took and often the payload. That one screen answers the first question: did the request reach you at all? A connection error or timeout points at your hosting or URL. A 4xx or 5xx points at your code.
Step 2: run a bare listener you control
To see the exact bytes, run a tiny listener that prints whatever arrives and replies 200. You can write one in a few lines in any language. A minimal version only needs to print the method, the path, every header and the raw body, then answer with an empty 200 response. Run it on a free local port such as 9000.
Your laptop is not reachable from the internet, so the provider cannot call it directly. Options, from simplest to most effort:
- Use the provider’s own command-line tool, if it has one, which forwards events to localhost.
- Use a tunnelling tool that gives your local port a temporary public address. Close the tunnel when you finish.
- Deploy the listener to a staging server for a short time.
Avoid pasting real deliveries into unknown public “request bin” websites. Payloads often contain names, emails and order details.
Step 3: save and replay
Save one captured body to event.json and note the headers. Now you can trigger your real handler with no provider involved:
curl -i -X POST localhost:3000/hooks/orders \
-H "Content-Type: application/json" \
-H "X-Signature: PASTE_CAPTURED_VALUE" \
--data-binary @event.json
Use --data-binary rather than -d. The -d flag strips newlines, which changes the bytes and makes signature checks fail for reasons unrelated to your code.
Diagnosing by symptom
| Symptom | Likely cause |
|---|---|
| Signature check fails only in production | A framework parsed the JSON before you read it, or a proxy changed the body |
| Provider shows timeouts | Your handler does slow work before replying |
| The same event is processed twice | A retry arrived and you do not record handled event IDs |
| 404 from your server | Trailing slash, wrong path prefix, or the route exists only for GET |
| Redirect status (301 or 308) | The URL uses the bare domain but your host forces www, or the reverse |
| Nothing arrives at all | Webhook not enabled for that event type, or a firewall rule |
Testing the unhappy paths
Once replay works, edit the saved file to test what production will eventually send you: an unknown event type (your code should log it and still return 200), a missing optional field, the same event ID twice, and a body with a tampered amount, which must fail the signature check.
Questions
Should my handler return an error when the event is invalid?
Return 400 or 401 for bad signatures so the sender sees the problem. For valid events you simply do not care about, return 200 so they are not retried forever.
How long will a provider keep retrying?
It depends on the provider. Read its documentation on retry schedules, and make your handler safe to run more than once.