Pick the tool for the question
"Testing a webhook" covers a few different questions, and each has a best tool:
| You want to know | Use |
|---|---|
| What does the provider actually send? | A request inspector such as webhook.site or our free webhook tester |
| Does my local code handle a real event? | A tunnel such as ngrok or cloudflared |
| How does my handler react to this exact payload? | curl or Postman |
| Does my code survive the event that broke production? | Replay a stored event |
webhook.site: see what is sent
webhook.site gives you a unique URL and shows every request sent to it, live in the browser: method, headers, query string and body. Paste the URL into a provider's settings, trigger an event, and you see exactly what arrives. It's the quickest way to answer "which header holds the signature?" or "what does this event's JSON look like?". HookStead's free webhook tester works the same way, with no sign-up.
Keep in mind:
- Requests are stored by a third party, and anyone with the URL can see them. Only send test data, never real customer data or live secrets.
- It only receives. It doesn't run your code or check signatures, and free URLs are temporary.
ngrok and cloudflared: real events to localhost
A tunnel gives a port on your machine a public HTTPS URL:
ngrok http 3000
# or
cloudflared tunnel --url http://localhost:3000Use the URL it prints as the webhook URL in the provider, and events reach your local server. ngrok also has a local inspector at http://localhost:4040 that lists every request and can replay one with a click, which is handy while you fix a handler.
Quick-start tunnels get a new address each time they start, so you have to update the provider after every restart. A reserved domain avoids that. More in how to test webhooks locally.
curl: send a signed test webhook
For a fast loop, send the event yourself. Most providers sign with HMAC-SHA256, and openssl can compute the same signature. A GitHub-style example:
SECRET="test_secret"
BODY='{"action":"opened","number":7}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST http://localhost:3000/webhooks/github \
-H "Content-Type: application/json" \
-H "X-GitHub-Event: pull_request" \
-H "X-Hub-Signature-256: sha256=$SIG" \
--data "$BODY"Send the body exactly as signed: printf '%s' avoids the trailing newline that echo adds, a classic reason for signature mismatches. Then change one character of the body and confirm your handler rejects it. The scheme is explained in webhook signature verification.
Postman: saved test webhooks with signatures
Postman is useful when a team shares a collection of test events. Create a POST request with a raw JSON body, then compute the signature in a pre-request script (Postman includes CryptoJS):
const body = pm.request.body.raw;
const secret = pm.environment.get("webhook_secret");
const sig = CryptoJS.HmacSHA256(body, secret).toString(CryptoJS.enc.Hex);
pm.request.headers.upsert({ key: "X-Hub-Signature-256", value: "sha256=" + sig });Postman sends requests from your machine, so it can call localhost directly without a tunnel. Add tests that check the status code, and run the collection in CI.
Provider CLIs
Some providers ship a CLI that forwards real, correctly signed events to localhost. The best known is Stripe's:
stripe listen --forward-to localhost:3000/webhooks/stripe
stripe trigger payment_intent.succeededstripe listen uses its own signing secret, different from your dashboard endpoint's. Mixing them up is the top cause of Stripe signature errors.
Replay real events
Hand-written payloads miss the details that break production: the optional field that is suddenly missing, the event that arrives before the one it depends on, the duplicate. The best test data is the events you actually received.
HookStead stores every event that reaches a source, with its headers and body (secrets redacted in the dashboard). Open any event and replay it to any destination, including a tunnel to your laptop. Each replay is freshly signed, so your verification code is tested too. See the docs to set up a source.
A test checklist
Whatever tool you use, check these before you ship:
- A valid signature is accepted; a wrong or missing one gets a 4xx and nothing happens.
- The same event sent twice is processed once. See idempotency.
- An unknown event type gets a 2xx and is ignored.
- The handler answers in well under a second, even when the work behind it is slow.
- Your production URL answers directly, with no redirect. See webhook URLs.
Frequently asked questions
- How do I test a webhook?
- Use a request inspector like webhook.site to see what the provider sends, a tunnel like ngrok to get real events on localhost, and curl or Postman to send signed test events to your handler.
- Is webhook.site safe to use?
- For test data, yes. Requests are stored by a third party and visible to anyone with the URL, so don't send real customer data or production secrets.
- Can Postman receive webhooks?
- Postman is built for sending requests. Use it to send test webhooks to your endpoint, and a request inspector or tunnel to receive them.
- Do I need ngrok to test webhooks?
- Only to receive real events from a provider on your laptop. To test your handler with a payload you already have, curl or Postman can call localhost directly.