DEV Community: Anonymily

Test Webhooks Locally Without ngrok

Anonymily — Tue, 23 Jun 2026 19:14:36 +0000

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.

Mastering Webhook Signature Verification in Local Dev

Anonymily — Tue, 23 Jun 2026 17:19:57 +0000

The 400 Bad Request Ghost

You’ve set up your listener, configured your tunnel, and triggered a test event from Stripe or GitHub. Everything looks perfect, but your console logs a cryptic error: Invalid signature or a blunt 400 Bad Request.

webhook signature verification is the primary security mechanism that ensures a request actually came from the provider and wasn't intercepted or forged. While the concept is simple—hash the payload with a shared secret and compare it to a header—the implementation is where most developers lose hours of productivity.

In this guide, we’ll look at why signature verification fails, how to fix it in your code, and how to improve your local development workflow using tools like Anonymily to stop the "trigger-fail-restart" cycle.

The Core Concept of Webhook Signature Verification

Most modern providers (Stripe, GitHub, Shopify, Slack) use HMAC (Hash-based Message Authentication Code). The process generally follows these steps:

The provider takes the raw JSON body of the request.
They sign it using a secret key only you and the provider know.
They send the signature in a header (e.g., Stripe-Signature or X-Hub-Signature-256).
Your server repeats the process and compares the resulting hashes.

If even one byte is different, the hashes won't match. This is by design, but it’s also why it’s so fragile during development.

The #1 Culprit: The "Raw Body" Mutation

The most common reason for failure in Node.js (Express/Fastify) is body parsing. By the time your webhook handler receives the request, a middleware like app.use(express.json()) has already parsed the body into a JavaScript object.

When you try to verify the signature, you might try to stringify that object back into JSON. This will almost always fail.

// DO NOT DO THIS
const payload = JSON.stringify(req.body);
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);

Why? Because JSON.stringify might change the whitespace, reorder keys, or handle character escaping differently than the original raw string sent by the provider. To fix this, you must capture the raw buffer before it gets parsed.

The Fix for Express

You need to use the verify callback in the JSON parser to attach the raw buffer to the request object:

app.use(express.json({
  verify: (req, res, buf) => {
    if (req.originalUrl.startsWith('/webhooks')) {
      req.rawBody = buf;
    }
  }
}));

// Then in your handler:
const event = stripe.webhooks.constructEvent(req.rawBody, sig, endpointSecret);

The Secret Mismatch and Environment Drift

It sounds obvious, but using the wrong secret is the second most common failure point. There are usually three different types of keys involved in any API integration:

API Keys: Used to make requests to the provider.
Production Webhook Secret: Used for your live endpoint.
Local/Test Webhook Secret: Specifically for your local tunnel or CLI.

If you are using a tool like stripe listen, it generates a unique local webhook secret that is different from the one in your Stripe Dashboard under "Endpoints." If you copy the secret from the dashboard but use a local tunnel, verification will fail every time.

Timing Attacks and Replay Protection

Providers like Stripe and Shopify include a timestamp in the signature header (e.g., t=1672531200,v1=...). This is to prevent "replay attacks," where a malicious actor intercepts a valid request and sends it again.

If your local machine's clock is significantly out of sync with the provider's servers (clock skew), the verification library will reject the request even if the signature is mathematically correct. This often happens if you've put your laptop to sleep and the system clock hasn't updated properly.

The Developer Workflow Problem

Even with the code fixed, debugging webhooks is painful. Most developers use a tunnel that gives them a random URL. Every time you restart the tunnel, you have to:

Copy the new URL.
Go to the Stripe/GitHub dashboard.
Update the webhook settings.
Trigger a new event.

Across a week of iterating, that copy-paste loop adds up to real lost time. Furthermore, if your local server is down when the webhook hits, that event is lost unless you manually trigger it again from the provider's UI.

Where a tool like Anonymily helps

Anonymily is a developer webhook inspector and local relayer designed to solve these specific frustrations. Instead of a random ephemeral URL, it provides a stable named endpoint that survives restarts and redeploys.

To start receiving webhooks locally, you just run:

npx @anonymilyhq/cli listen 3000

This command does two things: it captures webhooks in the cloud and forwards them 1:1 to your localhost over Server-Sent Events (SSE).

Why this helps with signature verification:

Capture even when offline: Anonymily captures requests even when your localhost is down. You can see exactly what the provider sent, including headers and the raw body.
One-Click Replay: If your signature verification fails, you don't need to trigger a new event from the provider. You can replay the captured request from the Anonymily dashboard. On the Pro plan, you can even edit the body or headers and re-sign the request to test different edge cases.
Synthetic Events: Testing specific scenarios (like a subscription.deleted event) can be hard to trigger manually. Anonymily Pro can generate provider-signed synthetic events for GitHub, Shopify, Slack, and more, so you can test your logic without touching the provider's dashboard.

Leveraging AI for Webhook Diagnosis

If you debug with an AI editor, Anonymily also ships an MCP (Model Context Protocol) server:

npx @anonymilyhq/mcp-server

If you use an AI-powered editor like Cursor or Claude Code, you can connect this MCP server to let the AI read your incoming webhook payloads, diagnose why a signature might be failing, and even suggest the exact code fix for your specific framework. It turns the "guess and check" process into a conversation.

Honest Framing: When NOT to use Anonymily

It is important to be clear: Anonymily is a development and testing tool. It is optimized for visibility, replaying, and debugging.

If you are looking for a production-grade webhook gateway to handle millions of events with high availability and retries for your live infrastructure, you should look at tools like Hookdeck or Svix. Anonymily is the tool you use on your machine to get the code right before you push to production.

Summary of the Fixes

To ensure your webhook signature verification works every time:

Always use the raw body buffer, never a stringified JSON object.
Check your secrets. Ensure the secret in your .env matches the specific endpoint you are hitting (Local vs. Prod).
Check your clock. Ensure your dev machine is synced via NTP.
Use stable URLs. Stop updating dashboards every time you restart your tunnel.

If you're tired of the manual setup, give Anonymily a try for free. You get one named endpoint and 48 hours of history out of the box.

Try it now:

npx @anonymilyhq/cli listen 3000

Learn more at https://anonymily.com.