Local Webhook Testing: How to Receive Webhooks on Localhost

You've built a webhook handler and you want to test it against real events before deploying. The problem: your provider sends a POST request to a public URL, and localhost:3000 isn't one. Stripe has no idea your laptop exists.

This is the first wall almost everyone hits building a webhook integration, and the fix is simple once you understand what's actually happening.

Why localhost doesn't work

Your provider's servers live somewhere on the public internet. When an event fires, they make an outbound HTTP request to whatever URL you configured. localhost only resolves to "this machine" on the machine that's running it. Stripe's servers have no route to your laptop, no matter how confidently you paste http://localhost:3000/webhooks into their dashboard.

The fix is a tunnel: a service that gives you a public URL and forwards every request it receives straight to your local port.

Provider → https://abc123.ngrok.io  →  tunnel service  →  localhost:3000

Setting up a tunnel

brew install ngrok
# or: npm install -g ngrok

npm run dev
# Server running on http://localhost:3000

ngrok http 3000
# Forwarding: https://abc123.ngrok.io -> http://localhost:3000

The URL-changes-every-restart problem

Free ngrok tunnels assign a new random subdomain each time you start one. Restart your dev session and the URL you configured in Stripe's dashboard is dead. You'll see failed test events with no obvious cause until you notice the URL in your terminal no longer matches the one in the provider dashboard.

A few ways around this:

# Paid ngrok plans support a fixed subdomain
ngrok http 3000 --domain=my-app.ngrok-free.app

Cloudflare Tunnel gives you a stable, named tunnel for free if you're willing to do a one-time setup against a domain you control. The tradeoff is a bit more configuration upfront in exchange for never touching the provider's dashboard again.

Testing without a live provider

Sometimes you don't need a real Stripe event, you just need to check that your handler parses the payload and responds correctly. curl gets you there faster than triggering a real event and waiting for it to arrive:

curl -X POST http://localhost:3000/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1699999999,v1=fake_for_local_testing" \
  -d '{"type": "payment_intent.succeeded", "data": {...}}'

This skips signature verification unless you compute a real HMAC, which is fine for testing your business logic in isolation but won't catch signature bugs. Most providers also offer a CLI that generates properly signed test events; Stripe's CLI (stripe trigger payment_intent.succeeded) and GitHub's gh webhook forward extension both do this and are worth the five minutes it takes to install them.

Replaying instead of re-triggering

Once you have a handler that mostly works, the slow part of iterating is often the provider itself: opening its dashboard, finding a test event, and firing it again just to check a one-line fix. If you're capturing events somewhere durable first (rather than pointing the provider straight at your tunnel), you can skip that round trip and just replay the stored payload against your local endpoint as many times as you need.

A workflow that scales past day one

Local tunnels are great for the first afternoon of wiring something up. They get annoying once you're testing regularly: URLs expire, you forget which tunnel is pointed where, and every teammate has to repeat the same setup on their own machine.

If you're already receiving events through Webhook Watchtower, local testing gets simpler: point a tunnel destination at your existing source instead of reconfiguring the provider, and replay any past event straight to your machine instead of triggering a new one. See the destinations guide for setting one up.