The ngrok Problem

If you've built against Stripe, GitHub, or Shopify webhooks, you know the friction: spin up ngrok, get a random URL, paste it into your provider's dashboard, wait for events, debug locally, restart ngrok (new URL), repeat. It works, but it's a loop that kills momentum.

The real issue isn't that you need a tunnel—it's that the tunnel is stateless and ephemeral. Every restart breaks the endpoint. Every new session is manual setup. For teams, sharing a tunnel URL adds complexity. And if you're testing signature verification or replay logic, you're stuck with whatever the provider sends, whenever they send it.

Let's look at what actually works to test webhooks locally, and when each approach makes sense.

Option 1: Local HTTP Server + Manual Testing

The simplest approach: run a local server, trigger events by hand, inspect the payload.

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', JSON.stringify(req.body, null, 2));
  console.log('Headers:', req.headers);
  res.status(200).json({ ok: true });
});

app.listen(3000, () => console.log('Listening on :3000'));

Then curl a fake event:

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"event": "charge.succeeded", "id": "test_123"}'

Pros:

• Zero dependencies, full control.
• Fast feedback loop.
• Easy to modify payloads and test edge cases.

Cons:

• You're not testing against real provider signatures.
• No way to test retry logic or delivery guarantees.
• Doesn't scale to multiple team members or CI/CD.

This is fine for unit-test-level webhook logic, but it's not integration testing.

Option 2: Tunneling (ngrok, Cloudflare Tunnel, Bore)

A tunnel exposes your local server to the internet so providers can reach it.

ngrok:

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

Then register https://abc123.ngrok.io/webhook in your provider's dashboard.

Cloudflare Tunnel:

cloudflared tunnel run --url http://localhost:3000 my-tunnel

Pros:

• Works with real providers and real events.
• Tests signature verification end-to-end.
• Widely known and documented.

Cons:

• URL changes on every restart (unless you pay for ngrok Pro).
• Manual dashboard updates each time.
• Latency and potential rate limits.
• Not ideal for team workflows—who owns the tunnel?
• No built-in request history or replay.

For one-off testing, it's acceptable. For iterative development, it's tedious.

Option 3: Stable Endpoint + Local Relay

A better approach: get a stable, named endpoint that survives restarts, and relay events to your local machine over a persistent connection.

With Anonymily, you run:

npx @anonymilyhq/cli listen 3000

You get a stable URL like https://api.anonymily.com/h/your-app that doesn't change. The CLI opens a Server-Sent Events connection to Anonymily's cloud, which forwards captured webhooks 1:1 to localhost:3000. If your local server restarts, the relay reconnects automatically.

Pros:

• Stable endpoint—register once, forget it.
• Survives local restarts and redeploys.
• Built-in request history and inspection.
• Replay individual events without re-triggering in the provider.
• Works offline: captures requests even if localhost is temporarily down.
• No ngrok URL juggling.

Cons:

• Not a production event gateway (use Hookdeck or Svix for that).
• Requires internet connection to the relay service.
• Free tier has limits (200 requests per hook, 48 hours history).

For development and testing, this removes the friction ngrok introduces.

Option 4: Docker + Compose for Isolation

If you're testing multiple services or want reproducible environments, use Docker:

version: '3'
services:
  webhook-receiver:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - .:/app
      - /app/node_modules

Run docker-compose up, then tunnel to localhost:3000 inside the container. This isolates your webhook handler from your host machine and makes CI/CD integration cleaner.

Pros:

• Reproducible environment.
• Easy to test against different Node versions or dependencies.
• Closer to production setup.

Cons:

• More overhead than a bare local server.
• Debugging requires extra setup (debugger ports, volume mounts).

Option 5: Mock Provider Events in Tests

For unit and integration tests, mock the webhook payload entirely:

const request = require('supertest');
const app = require('./app');

describe('POST /webhook', () => {
  it('should process a charge.succeeded event', async () => {
    const payload = {
      id: 'evt_123',
      type: 'charge.succeeded',
      data: {
        object: {
          id: 'ch_456',
          amount: 2000,
          currency: 'usd'
        }
      }
    };

    const res = await request(app)
      .post('/webhook')
      .set('Content-Type', 'application/json')
      .send(payload);

    expect(res.status).toBe(200);
    expect(res.body.ok).toBe(true);
  });
});

Pros:

• Fast, deterministic, no external dependencies.
• Easy to test error cases and edge cases.
• CI/CD friendly.

Cons:

• Doesn't test against real provider signatures or timing.
• Requires maintaining mock payloads as provider APIs evolve.

Use mocks for unit tests, and a real endpoint for integration tests.

Signature Verification

Whichever method you choose, verify HMAC signatures locally. Providers (Stripe, GitHub, Shopify) sign requests with a secret. Your handler must validate the signature before processing:

const crypto = require('crypto');

function verifySignature(req, secret) {
  const signature = req.headers['x-webhook-signature'];
  const body = req.rawBody; // Must be raw bytes, not parsed JSON
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

app.post('/webhook', (req, res) => {
  if (!verifySignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process webhook
  res.status(200).json({ ok: true });
});

Note: you need req.rawBody (the raw bytes before JSON parsing). In Express, use express.raw({ type: 'application/json' }) or a custom middleware.

Choosing Your Approach

Local server only: Quick logic checks, no external dependencies. Skip for real provider testing.

Manual curl requests: Same as above, but you control the payload. Good for edge cases.

ngrok or Cloudflare Tunnel: When you need real provider events and don't mind URL churn. Fine for occasional testing.

Stable endpoint + relay: Best for iterative development. Register once, restart freely, inspect history, replay events. Removes the ngrok friction.

Docker: When reproducibility and CI/CD integration matter more than speed.

Mocked events in tests: Always. Unit tests should be fast and deterministic. Use real endpoints only for integration tests.

Most teams use a mix: mocks in CI, a stable local endpoint for dev, and real provider events in staging.

Getting Started

If you want to test webhooks locally without the ngrok restart loop, try a stable endpoint approach. With Anonymily, you can get one in seconds:

npx @anonymilyhq/cli listen 3000

You'll get a stable URL, built-in request history, and replay without re-triggering events. The free tier covers most development workflows.

Head to https://anonymily.com to learn more and sign up.