How to Test a Webhook (and Why It Fails in Production)

Step one: see what is actually sent

Documentation describes a webhook; the real request is what your code must handle. Before writing a handler, point the service at a temporary URL that records incoming requests, trigger the event, and read what arrives: the method, the headers, and the exact body.

You will often find something the docs did not make clear: a field that is a string rather than a number, an event wrapped one level deeper than expected, or a signature header with a slightly different name.

Step two: replay it against your own endpoint

Once you have a real payload, you can send it to your own endpoint as many times as you like with an API client, without waiting for a real payment or signup each time. Copy the headers along with the body, because many handlers check the content type or the signature header.

curl -X POST https://your-app.test/webhooks/payments \
  -H "Content-Type: application/json" \
  -H "X-Signature: t=1728000000,v1=5257a8..." \
  -d @payload.json

A local server is not reachable from the internet, so a real provider cannot call it directly. For a live test from the provider, use a tunnelling tool that gives your local port a public URL, or deploy the handler to a test environment.

Verify the signature

Your webhook URL is public, so anyone can send it a request that looks like a payment. Most providers sign each request with a secret only you and they know, usually an HMAC of the raw body, and put the result in a header. Your handler must recompute it and reject the request if it does not match.

Many providers also include a timestamp in what they sign. Reject requests older than a few minutes, so a captured request cannot be replayed later.

Why it works in testing and fails in production

• Slow responses: providers wait only a few seconds. If your handler sends emails or calls other APIs before replying, it times out and the provider marks the delivery failed. Reply with a 2xx immediately and do the slow work in a background job.
• Retries: when a delivery fails, the provider sends it again, sometimes many times over hours or days. Your handler will see the same event more than once.
• Duplicates and order: even successful events can arrive twice or out of order. Store each event's ID and skip any you have already processed, so a repeated payment event does not ship an order twice.
• Wrong status codes: returning 200 for a request you could not process tells the provider all is well, and it will not retry. Return an error status when you genuinely failed.