Guide
How to Test Webhooks Locally (Without a Tunnel)
Webhook providers can only call public URLs, and your development server is not one. Here are three ways to close that gap, from simplest to most involved.
1. Capture once, replay with cURL
You rarely need a live connection while writing a handler. You need one realistic request that you can send again and again.
- Create a webhook URL and register it with your provider.
- Trigger the event. The request appears in the inspector.
- Press cURL on the request. You get a command that reproduces it exactly, headers and body included.
- Change the URL in the command to
http://localhost:3000/your-routeand run it as often as you like.
Signatures stay valid when you replay this way, because the body and the signature header are unchanged. The exception is schemes with a timestamp tolerance, such as Stripe and Slack: after five minutes, strict verification will reject the replay. Loosen the tolerance in development, or use the next method.
2. Stream requests to localhost as they arrive
Every webhook.stream endpoint exposes its requests as a Server-Sent Events stream. A small forwarder follows that stream and replays each request against your local server the moment it arrives:
curl -fsSL https://webhook.stream/cli.js | node - \
--id <endpoint id> \
--key <dashboard key> \
--to http://localhost:3000/webhooksThe inspector fills in the ID and key for you under Stream → Forward to localhost. Your machine makes an outbound connection only, so this works behind corporate firewalls and NAT, and nothing on your network is exposed to the internet.
The provider still gets its fast 200 from the edge, so a breakpoint in your debugger never causes a timeout or a retry storm on the provider's side.
3. A tunnel
Tunnelling tools give your local server a temporary public URL. They are the right choice when the provider must read your application's real response, for example Twilio reading TwiML that your code generates, or when you are testing a browser flow rather than a webhook.
The costs are an agent to install and keep running, a URL that often changes between sessions and has to be re-registered, and a path from the public internet to your laptop.
Which one should you use?
| Situation | Use |
|---|---|
| Writing or debugging a handler | Capture and replay with cURL |
| Testing a full flow end to end | Stream to localhost |
| The provider needs your app's actual response | A tunnel, or a templated response on the test URL |
| A CI job needs to receive a webhook | The stream API |
Tips that save time
- Keep one stable URL registered. Leave your webhook.stream URL in the provider's dashboard and forward from it. You stop re-registering tunnel URLs every morning.
- Save interesting payloads. Export requests as JSON and commit a few as test fixtures.
- Test the failure path. Set the test URL to answer
500, or to delay its answer, and watch how the provider retries.