Lorixen.
EN

Testing webhooks on your laptop: tunnels and CLI forwarding

Short answer: Webhooks need a public HTTPS address, but your app in development runs on localhost, which the outside world can't reach. Three practical ways to bridge that gap: use the provider's own CLI to forward events to your laptop (Stripe's stripe listen --forward-to is the best-known), use a webhook relay channel such as smee.io, or open a temporary tunnel that gives your local server a public URL. Treat tunnels as temporary, keep signature checks on, and record real payloads so you can replay them in tests.

Why local webhook testing is awkward

When you build an integration with a payment provider, a booking platform or a code host, events arrive as HTTP requests to a URL you register. During development:

  • Your app is on localhost, behind your home or office router.
  • Deploying to a staging server for every change is slow.
  • Faking requests by hand misses details like signature headers and real payload shapes.

The result is code that "works" with hand-written test data and fails on the first real event. Getting real events onto your laptop shortens the loop dramatically.

Option 1: the provider's CLI

Some providers ship a command-line tool that connects to your account and forwards events locally. Stripe's webhook documentation shows the pattern:

stripe listen --forward-to localhost:4242/webhook

The CLI receives events from your Stripe account in test mode and forwards them to your local endpoint. When it starts, it prints a webhook signing secret for the session; configure your local app with that secret so signature verification works exactly as in production. You can then trigger test events from another terminal, or by performing actions in test mode, and watch your handler process them.

Advantages:

  • No public URL is exposed; the CLI pulls events through its own connection.
  • Signatures are real, so you test verification code too.

Check whether your other providers offer something similar before reaching for a general tunnel.

Option 2: a webhook relay channel

GitHub's guide to testing webhooks demonstrates using smee.io: you create a channel in the browser, which gives you a public "webhook proxy URL", register that URL with the provider, then run a small client locally that receives events from the channel and forwards them to your local server.

This works with any provider that sends standard HTTP webhooks. Be aware that the channel URL is effectively public: anyone who knows it can see what's sent through it. Use it only with test data, and create a fresh channel when you're done.

Option 3: a temporary tunnel

A tunnel gives your local server a temporary public HTTPS address. Cloudflare's Quick Tunnels documentation describes running cloudflared tunnel --url http://localhost:8080, which prints a temporary trycloudflare.com address. It notes that anyone with the URL can access your local service, that the URL stops working when you stop the process, and that Quick Tunnels are intended for testing and development. Several other tunnel services exist with similar features; compare their current free limits and terms.

Tunnels are the most flexible option: they work for any provider and also let you open your local app on a phone or show it to a colleague. They also carry the most risk, because your development server is reachable from the internet while the tunnel runs.

Stay safe while testing

Whichever option you use:

  • Use test or sandbox modes, never live accounts with real customer data.
  • Keep signature verification switched on, using the test signing secret, so you exercise the real code path.
  • Don't expose admin panels or debug tools through a tunnel. If your development server has a debug console, a public tunnel makes it public too.
  • Stop tunnels when you finish, and don't leave them running overnight.
  • Don't commit temporary URLs or secrets into configuration files.

Record payloads for repeatable tests

Real events are great for exploration, but you also want automated tests that don't depend on a live connection:

  1. While testing, log the raw request bodies and headers your endpoint receives, with secrets removed.
  2. Save representative examples, including awkward ones like refunds, failed payments and cancellations, as test fixtures.
  3. Write tests that send those fixtures to your handler and check the outcome.
  4. For signature checks in tests, sign fixtures with a test secret using the same algorithm the provider uses, or use the provider's library helpers where available.

Now your test suite covers real payload shapes, and CI can run it without any tunnel.

Share the setup with the team

Write the steps into the project's README: which tool to install, the exact command, which test secret to put in the local environment file, and which events to trigger for common scenarios. A new developer, or you in six months, can then test the integration in minutes instead of rediscovering the setup.

Use the provider's delivery tools

Many providers keep a log of webhook deliveries. GitHub's documentation, for example, covers viewing and redelivering past deliveries. When a local test fails, resending the same event after fixing your code is much faster than reproducing the action that caused it.

A worked example

Imagine a hypothetical Winnipeg music-lesson booking platform integrating card payments and a calendar service. The developer had been testing webhooks by deploying to staging after every change, which took several minutes each time. They switched to the payment provider's CLI forwarding for payment events and a temporary tunnel for the calendar service's notifications, kept signature checks on with test secrets, and saved a dozen real payloads as fixtures. Handler changes could now be tested in seconds, and the fixtures became the integration's regression tests.

FAQ

Can I use a tunnel in production?

Quick, temporary tunnels aren't meant for it. Production webhooks should go to a properly hosted, monitored endpoint.

Why does my signature check fail locally?

Usually because the local app uses a different signing secret from the one the forwarding tool or test endpoint uses. Check which secret the session printed.

Do I need HTTPS locally?

The public side of a tunnel or relay provides HTTPS. Your local server can usually stay on plain HTTP behind it.

If you're building an integration and testing webhooks is slowing you down, tell us which services you're connecting.

Sources

WhatsAppBook a call