How to test webhooks, end to end

A webhook test that only checks "my endpoint returned 200" misses most real failures. This page is a test plan: start from a real delivery, check the exact bytes your handler verifies, then reproduce what providers actually do in production: retries, duplicates, reordering and slow responses.
Get a free webhook URL Free, no account needed.

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:

The three parts of a webhook integration
PartWhat can go wrongHow you find out
DeliveryWrong URL, a route that doesn't exist, HTTPS or firewall problems, auth or CSRF middleware rejecting the requestPoint the provider at a URL that records everything it receives
Verification and parsingSignature computed over a re-serialized body, the wrong secret, an unexpected Content-Type or charsetRun your handler against the exact captured bytes and headers
BehaviourDouble-processing a retried event, events arriving out of order, slow handlers timing outReplay 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:

Request
curl -i https://hookwatcher.com/<endpoint-id> \
  -H 'Content-Type: application/json' \
  -d '{"event":"order.created","order_id":"ord_1042","total":4999}'
Response
HTTP/1.1 200 OK
content-type: application/json

{
  "received": true,
  "method": "POST",
  "bodySize": 60
}
The response is HookWatcher's default for an endpoint without a custom response. 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 endpoint
Create a real endpoint, send it a request from this page and one from your terminal, and see exactly what HookWatcher recorded for each.
No account. The endpoint is yours in this browser and also opens in the playground.

2. Read what arrived

For each provider you integrate, note four things from a captured delivery before writing code:

  1. 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.
  2. The event type. Some providers put it in a header (GitHub's X-GitHub-Event, Shopify's X-Shopify-Topic), others only in the body (Stripe's type).
  3. A unique delivery or event ID. You'll need it to ignore duplicates.
  4. The Content-Type. Most providers send JSON, but Slack slash commands and Twilio send application/x-www-form-urlencoded.
Headers worth recording for common providers
ProviderSignatureEvent typeUnique ID
StripeStripe-Signaturebody: typebody: id (evt_…)
GitHubX-Hub-Signature-256X-GitHub-EventX-GitHub-Delivery
ShopifyX-Shopify-Hmac-Sha256X-Shopify-TopicX-Shopify-Webhook-Id
RazorpayX-Razorpay-Signaturebody: eventx-razorpay-event-id
Slack (Events API)X-Slack-Signaturebody: event.typebody: 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):

Terminal
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:

Provider behaviour and how to test it
BehaviourWhat breaksTest
Retries after a timeout or 5xxThe order is fulfilled twice, the email sent twiceDelayed duplicate replay
Duplicate deliveriesSame as above, without any error on your sideReplay one event several times
Concurrent duplicatesTwo workers both pass the "already processed?" checkConcurrent replay
Out-of-order eventsA refund handled before the payment it refundsReplay a sequence in another order
Forged or stale requestsUnsigned requests acceptedInvalid 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=:

Shell
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-raw or --data-binary @file.json. -d @file strips newlines from files, which changes the bytes and the signature.
  • printf '%s' avoids the trailing newline echo adds.
  • 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

The playground gives you a live URL right away. Point a provider's test event at it, or use the curl command above, and inspect exactly what arrives.
Get a free webhook URL No account or card needed. Want to keep it? Create a free account

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.

Sources