Mastering Webhook Signature Verification in Local Dev

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:

1. The provider takes the raw JSON body of the request.
2. They sign it using a secret key only you and the provider know.
3. They send the signature in a header (e.g., Stripe-Signature or X-Hub-Signature-256).
4. 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:

1. API Keys: Used to make requests to the provider.
2. Production Webhook Secret: Used for your live endpoint.
3. 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:

1. Copy the new URL.
2. Go to the Stripe/GitHub dashboard.
3. Update the webhook settings.
4. 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:

1. 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.
2. 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.
3. 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:

1. Always use the raw body buffer, never a stringified JSON object.
2. Check your secrets. Ensure the secret in your .env matches the specific endpoint you are hitting (Local vs. Prod).
3. Check your clock. Ensure your dev machine is synced via NTP.
4. 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.

Comments

[Alex Shev]

Signature verification belongs before business logic, even in local dev. It is easy to debug the happy path and accidentally train the team to trust payloads before proving they came from the sender.