How to test webhooks, end to end
By the HookWatcher team · Updated
What a webhook test covers
A webhook integration has three parts that fail in different ways, so test them separately:
| Part | What can go wrong | How you find out |
|---|---|---|
| Delivery | Wrong URL, a route that doesn't exist, HTTPS or firewall problems, auth or CSRF middleware rejecting the request | Point the provider at a URL that records everything it receives |
| Verification and parsing | Signature computed over a re-serialized body, the wrong secret, an unexpected Content-Type or charset | Run your handler against the exact captured bytes and headers |
| Behaviour | Double-processing a retried event, events arriving out of order, slow handlers timing out | Replay one real event several times, in a different order or after a delay |
Most tutorials stop at the first row. The bugs that reach production are usually in the second and third.
1. Capture a real delivery first
Before writing handler code, find out what the provider really sends. Payload documentation is often incomplete: fields can be null, nested objects can be missing for some event types, and the headers you need (signature, event type, delivery ID) are rarely shown in full.
Create an endpoint in the playground (no account needed), paste its URL into the provider's webhook settings and trigger a test event. You can also send your own request to check the endpoint works:
curl -i https://hookwatcher.com/<endpoint-id> \
-H 'Content-Type: application/json' \
-d '{"event":"order.created","order_id":"ord_1042","total":4999}'HTTP/1.1 200 OK
content-type: application/json
{
"received": true,
"method": "POST",
"bodySize": 60
}bodySize is the number of bytes received. Abridged: the status line depends on the HTTP version curl uses, and the response also carries headers such as hw-request-id. Replace <endpoint-id> with your endpoint's ID.The request appears in the inspector immediately, with every header, the query string and the body exactly as sent. Header order and case are stored too, and replays use them. Try it here:
Try it: capture a delivery
Live, on a real endpoint2. Read what arrived
For each provider you integrate, note four things from a captured delivery before writing code:
- The signature header and its format. Is it hex or Base64? Is a timestamp signed along with the body? Your verification code has to rebuild exactly the same string.
- The event type. Some providers put it in a header (GitHub's
X-GitHub-Event, Shopify'sX-Shopify-Topic), others only in the body (Stripe'stype). - A unique delivery or event ID. You'll need it to ignore duplicates.
- The Content-Type. Most providers send JSON, but Slack slash commands and Twilio send
application/x-www-form-urlencoded.
| Provider | Signature | Event type | Unique ID |
|---|---|---|---|
| Stripe | Stripe-Signature | body: type | body: id (evt_…) |
| GitHub | X-Hub-Signature-256 | X-GitHub-Event | X-GitHub-Delivery |
| Shopify | X-Shopify-Hmac-Sha256 | X-Shopify-Topic | X-Shopify-Webhook-Id |
| Razorpay | X-Razorpay-Signature | body: event | x-razorpay-event-id |
| Slack (Events API) | X-Slack-Signature | body: event.type | body: event_id |
Provider deep dives: Stripe webhook testing and GitHub webhook testing. Check each provider's documentation for the full list; headers get added over time. The webhook inspector page goes through a captured request line by line.
3. Run it against your handler
Your handler runs on localhost, which providers can't reach. Rather than copying the payload into a curl command (which loses headers and usually reformats the JSON, breaking the signature), deliver the captured request itself. With hwcli, which works with endpoints in your account (create one with hwcli hooks create, or sign in on the web):
hwcli login hwcli listen <endpoint> --forward http://localhost:8080/webhooks --include-sensitive # later, once you've changed the handler: hwcli replay <event-id> --target :8080/webhooks
--include-sensitive passes signature headers through so your real verification code runs. Each delivery is printed with your server's status code and timing. The local webhook development guide covers the details.
4. Test what providers do in production
Providers deliver at least once, not exactly once. Your handler will eventually see the same event twice, events in the wrong order, and its own slow responses treated as failures. Test each of these deliberately:
| Behaviour | What breaks | Test |
|---|---|---|
| Retries after a timeout or 5xx | The order is fulfilled twice, the email sent twice | Delayed duplicate replay |
| Duplicate deliveries | Same as above, without any error on your side | Replay one event several times |
| Concurrent duplicates | Two workers both pass the "already processed?" check | Concurrent replay |
| Out-of-order events | A refund handled before the payment it refunds | Replay a sequence in another order |
| Forged or stale requests | Unsigned requests accepted | Invalid and missing signatures |
Once a fix works, save the event and the response your handler should give as a regression test so the bug stays fixed.
Testing with curl alone
curl is fine for checking routing and parsing, as long as you send the body byte for byte and sign it yourself. This GitHub-style request computes X-Hub-Signature-256 with OpenSSL. GitHub signs the raw body with HMAC-SHA256 and sends the hex digest prefixed with sha256=:
SECRET='your-webhook-secret'
BODY='{"zen":"Keep it logically awesome.","hook_id":1}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -i http://localhost:3000/webhooks/github \
-H 'Content-Type: application/json' \
-H 'X-GitHub-Event: ping' \
-H "X-Hub-Signature-256: sha256=$SIG" \
--data-raw "$BODY"- Use
--data-rawor--data-binary @file.json.-d @filestrips newlines from files, which changes the bytes and the signature. printf '%s'avoids the trailing newlineechoadds.- A hand-made payload only has the fields you remembered to add. Use a captured delivery when you can.
To check a signature without a terminal, use the webhook signature generator. It runs in your browser and shows the exact string being signed.
Pre-launch checklist
- The handler verifies the signature over the raw request body, before any JSON parsing.
- Requests with a missing or wrong signature get a 4xx and change nothing.
- Where the provider signs a timestamp, old requests are rejected (replay protection).
- The handler returns a 2xx quickly and does slow work in a background job.
- Processing the same event ID twice has no extra effect, including when both arrive at once.
- Events that arrive "early" (an update before a create) are handled or safely retried.
- Unknown event types are acknowledged and ignored, not answered with a 500 that triggers retries.
- Test and live mode use different secrets, and both are configured.
Create a free webhook endpoint and send your first request
Frequently asked questions
Can I test webhooks without deploying my app?
Yes. Point the provider at a capture URL, then deliver captured requests to localhost with hwcli listen, or give your local server a public URL with a tunnel. Neither needs a deployment or a port opened on your network.
Why does my signature check pass in tests but fail with real deliveries?
Usually because the test signs a re-serialized body. Frameworks that parse JSON before your handler runs (for example express.json()) give you an object, and JSON.stringify of it is not the bytes the provider signed. Verify against the raw body. See signature mismatches.
Do I need the provider's CLI to test its webhooks?
No. Provider CLIs (such as the Stripe CLI) are useful for triggering events, but any test event the provider's dashboard sends can be captured and replayed. Use whichever triggers the event types you need.
What status code should my webhook endpoint return?
A 2xx as soon as the request is verified and safely stored. Most providers treat any other status, and slow responses, as failures and retry. Return 4xx for requests you will never accept (bad signature) and 5xx only for temporary problems.