How to Test Webhooks on Localhost: Complete Developer Guide

The Localhost Problem

When developing locally, your application typically runs on http://localhost:3000 or a similar local address. External services like Stripe, GitHub, or Shopify cannot reach this address because it's behind your router's NAT, your firewall, or simply not connected to the public internet.

This creates a fundamental challenge: webhooks need a publicly accessible URL to deliver events. You can't tell Stripe to send webhook events to http://localhost:3000/webhooks — it would simply fail with a connection error.

Fortunately, there are several proven approaches to solve this problem, each with its own trade-offs. Let's explore the three main strategies developers use for local webhook testing.

Approach 1: Capture and Replay (Recommended)

The simplest and most reliable approach is to capture webhook payloads online and replay them locally. This two-step process separates the "receiving" from the "processing" and gives you complete control over both.

Step 1: Capture with Requex.me

Visit Requex.me and copy your unique webhook URL. Configure your provider (Stripe, GitHub, etc.) to send webhooks to this URL. Trigger an event and the incoming request appears instantly in your dashboard.

Inspect the full request — headers, body, query parameters. Copy the JSON payload to your clipboard using the built-in copy button.

Step 2: Replay Locally with cURL

Now paste the captured payload into a cURL command and send it to your local server:

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: abc123..." \
  -d '{"type":"payment_intent.succeeded","data":{"object":{...}}}'

This approach has several advantages: you can replay the same event dozens of times while debugging, you don't need any tunnel software, and you can modify the payload to test edge cases before sending it.

Approach 2: Tunneling (ngrok, Cloudflare Tunnel)

Tunneling creates a public URL that forwards traffic directly to your local server. The most popular tool is ngrok, which creates a secure tunnel from a public URL to your localhost.

# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Start a tunnel to your local server
ngrok http 3000

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

Copy the https://abc123.ngrok.io URL and use it as your webhook endpoint. All requests will be forwarded to your local server in real-time.

Pros and Cons of Tunneling

Approach 3: Provider CLI Tools

Some webhook providers offer their own CLI tools that can forward events to your localhost. These are often the most reliable option because they're purpose-built for their specific webhook format.

Stripe CLI

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to your Stripe account
stripe login

# Forward webhook events to your local server
stripe listen --forward-to localhost:3000/api/webhooks

# Trigger a test event
stripe trigger payment_intent.succeeded

GitHub CLI

GitHub doesn't have a built-in forwarding CLI, but you can use their webhook delivery logs in the repository settings to redeliver events. Combined with a tunnel, this provides a complete local testing experience.

When No CLI Exists

For providers without a CLI tool (most smaller SaaS platforms), the capture-and-replay approach with Requex.me is your best bet. It works universally with zero provider-specific setup.

Comparison: Which Approach Should You Use?

Best Practices for Local Webhook Development