SpunkArt
Websites, APIs and search

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

SymptomLikely cause
Signature check fails only in productionA framework parsed the JSON before you read it, or a proxy changed the body
Provider shows timeoutsYour handler does slow work before replying
The same event is processed twiceA retry arrived and you do not record handled event IDs
404 from your serverTrailing 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 allWebhook 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.