Loading...
Loading...
Your local development server runs on localhost:3000, but webhook providers can't reach it. Here are the best approaches to test webhooks during local development.
When Stripe, GitHub, or any other service sends a webhook, they need a publicly accessible URL. Your development machine is behind a router/firewall and uses a private IP address that the internet can't reach.
External services cannot reach your local server directly
The simplest approach is to capture webhooks with a service like Webhook.it, inspect the payload, then replay it locally. This works great for development and debugging.
Get a URL from Webhook.it and configure your webhook provider to send events there.
Trigger a test event and view the captured webhook on Webhook.it. Copy the JSON payload.
Use curl to send the captured payload to your local server:
curl -X POST http://localhost:3000/api/webhooks \
-H "Content-Type: application/json" \
-d '{
"id": "evt_captured_123",
"type": "payment_intent.succeeded",
"data": { ... }
}'Advantage: Simple, no additional tools needed. Great for understanding payload structure before writing handler code.
Save captured payloads as JSON files and use them in your automated tests. This approach scales well and doesn't require network access during testing.
// fixtures/stripe-checkout-completed.json
{
"id": "evt_1234567890",
"type": "checkout.session.completed",
"data": {
"object": {
"id": "cs_test_abc123",
"amount_total": 2000,
"currency": "usd"
}
}
}
// __tests__/webhooks.test.js
import payload from './fixtures/stripe-checkout-completed.json';
test('handles checkout completed', async () => {
const response = await handleWebhook(payload);
expect(response.status).toBe(200);
});Tunneling tools create a public URL that forwards traffic to your localhost. This allows real-time webhook delivery to your local server.
# Using ngrok ngrok http 3000 # Output: # Forwarding https://abc123.ngrok.io -> http://localhost:3000 # Use the ngrok URL as your webhook endpoint: # https://abc123.ngrok.io/api/webhooks
Pros
Cons
Common curl commands for testing webhooks locally:
Simple POST request
POST with custom headers
POST from file
| Approach | Best For | Setup |
|---|---|---|
| Capture + Replay | Initial development | None |
| Test Fixtures | Automated testing | None |
| Tunnel (ngrok) | Real-time testing | Install required |
Start with Capture + Replay using Webhook.it. It's the fastest way to understand webhook payloads without installing anything. Once you understand the payload structure, save them as test fixtures for automated testing. Only set up a tunnel if you need to test real-time flows or signature verification.