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.

  1. Create a webhook URL and register it with your provider.
  2. Trigger the event. The request appears in the inspector.
  3. Press cURL on the request. You get a command that reproduces it exactly, headers and body included.
  4. Change the URL in the command to http://localhost:3000/your-route and 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:

Forward live webhooks to localhost
curl -fsSL https://webhook.stream/cli.js | node - \
  --id  <endpoint id> \
  --key <dashboard key> \
  --to  http://localhost:3000/webhooks

The 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?

SituationUse
Writing or debugging a handlerCapture and replay with cURL
Testing a full flow end to endStream to localhost
The provider needs your app's actual responseA tunnel, or a templated response on the test URL
A CI job needs to receive a webhookThe 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.