DEV Community: Gerald Mitchell

GitHub webhook signature mismatch? 5 reasons X-Hub-Signature-256 won't verify (Node and Python fixes)

Gerald Mitchell — Fri, 09 Oct 2026 17:03:13 +0000

Disclosure: I run webhook-relay.gmitchell-relay.workers.dev, a free site with webhook error fix pages. This article was written with AI assistance and reviewed before publishing.

You set up a GitHub webhook, add a secret, write ten lines of HMAC code, and every delivery comes back 401 signature mismatch. The code usually looks right. Something about the inputs is wrong. Here's how GitHub signs deliveries and the five things that most often break verification.

How GitHub signs a delivery

For every delivery, GitHub computes an HMAC-SHA256 over the raw request body, keyed with your webhook secret. It sends the result hex-encoded with a prefix:

X-Hub-Signature-256: sha256=3f5a...e9

To verify, you compute the same HMAC over the exact bytes you received and compare it to the header in constant time. Any byte difference in the body, the secret, or the encoding produces a mismatch.

1. No secret is configured, so there's no header

If the webhook in Settings → Webhooks has no secret, GitHub doesn't send X-Hub-Signature-256 at all. Your code ends up comparing against undefined or an empty string.

Fix: set a secret on the webhook, and make your handler reject requests with a missing header explicitly. A missing header should get a clear 401, not a crash.

2. Wrong header or wrong algorithm

X-Hub-Signature (no -256) is the legacy SHA-1 signature. If you read that header but compute SHA-256, or the other way round, nothing will ever match. Also remember the value starts with sha256=. Compare against "sha256=" + hexDigest, or strip the prefix first.

3. You hashed parsed JSON, not the raw body

This is the most common cause. If a body parser (express.json(), a framework default) already turned the body into an object, JSON.stringify(req.body) won't reproduce GitHub's bytes. Whitespace, key order and unicode escaping all differ.

Fix: hash the raw bytes. In Express, use express.raw() on the webhook route only. In Flask, use request.get_data().

4. The webhook's content type is form-encoded

If the webhook's Content type is application/x-www-form-urlencoded, GitHub signs the whole form body (payload=%7B%22...), not the decoded JSON inside it. Code that extracts payload and hashes it will fail.

Fix: switch the webhook to application/json, or hash the raw form body exactly as received.

5. The secret isn't the one you think

Common variations:

a trailing newline or space in the env var (very common when the value came from echo or a .env file)
a different secret per webhook, so the repo webhook and the org webhook don't share one
a GitHub App's webhook secret vs a repository webhook's secret

Fix: if in doubt, set a fresh secret on the webhook and in your env, then redeploy.

Working code: Node.js (Express)

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

const app = express();
const SECRET = process.env.GITHUB_WEBHOOK_SECRET;

// Raw body on the webhook route only, registered before any global express.json()
app.post('/github/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Hub-Signature-256');
  if (!header) return res.status(401).send('missing signature');

  const expected = 'sha256=' +
    crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  // timingSafeEqual throws if lengths differ, so check first
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('signature mismatch');
  }

  const event = req.get('X-GitHub-Event');
  const payload = JSON.parse(req.body.toString('utf8'));
  // ... handle event ...
  res.sendStatus(204);
});

app.use(express.json()); // everything else

app.listen(3000);

Check that req.body is a Buffer here. If it's an object, a parser already ran and the raw bytes are gone.

Working code: Python (Flask)

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["GITHUB_WEBHOOK_SECRET"].encode()

@app.post("/github/webhook")
def github_webhook():
    header = request.headers.get("X-Hub-Signature-256", "")
    body = request.get_data()  # raw bytes; call before request.json
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not header or not hmac.compare_digest(header, expected):
        abort(401)
    event = request.headers.get("X-GitHub-Event")
    payload = request.get_json()
    # ... handle event ...
    return "", 204

Debugging tips

In Settings → Webhooks → Recent Deliveries, you can see the exact headers and payload GitHub sent, and Redeliver a delivery after each fix instead of waiting for a new event.
Temporarily log the raw body length, the received header, and the first few characters of your computed digest. Don't log the secret. If the body length differs from what GitHub shows, something between GitHub and your code changed the bytes (a proxy, a body parser, or re-encoding).
If you're behind a reverse proxy or tunnel, make sure it passes the body through unmodified.

Summary

Symptom	Likely cause
Header missing	No secret set on the webhook
Never matches, even with a correct secret	Hashing parsed JSON, wrong algorithm, or missing `sha256=` prefix
`payload=` in the body	Form-encoded content type
Worked before a redeploy	Secret changed, or whitespace in the env var

The full checklist, kept up to date, is on our free page: GitHub webhook signature mismatch.

Shopify webhook HMAC verification failed: causes and fixes (Node, Remix, Express)

Gerald Mitchell — Fri, 09 Oct 2026 13:04:33 +0000

You register a Shopify webhook, trigger a test order, and your handler rejects it with a 401. The header is there, the secret looks right, and the digest still doesn't match. This post covers what Shopify actually signs, the mistakes that cause most mismatches, and verification code you can paste into plain Node, Express or a Remix / React Router app.

What Shopify signs

Every HTTPS webhook delivery includes an X-Shopify-Hmac-Sha256 header. Its value is:

base64( HMAC-SHA256( key = your app's client secret, message = raw request body ) )

That's it. There is no timestamp and no prefix. Your job is to recompute the same value from the bytes you received and compare it to the header. Every failure comes down to one of three inputs being different from what Shopify used: the bytes, the key, or the encoding.

Cause 1: you hashed parsed JSON instead of the raw body

This is the most common one by far. If express.json() (or any body parser) runs first, req.body is a JavaScript object. Calling JSON.stringify(req.body) doesn't give you back the original bytes: key order, whitespace, escaped slashes and Unicode escapes (\u00e9 vs é) can all change. One different byte gives you a completely different HMAC.

Fix: hash the raw Buffer that came off the wire, and make sure no JSON parser touches the webhook route before you verify it.

Cause 2: comparing hex to base64

Node's digest() defaults to returning a Buffer, and plenty of copy-pasted examples (often from Stripe or GitHub integrations) use .digest('hex'). Shopify's header is base64. A hex digest will never equal it, even when everything else is correct.

Fix: use .digest('base64'), or compare the decoded bytes, as shown below.

Cause 3: the wrong secret

The key is your app's client secret (sometimes labelled "API secret key" in the Partner Dashboard or Dev Dashboard). It's not:

the client ID / API key,
an Admin API access token (shpat_...),
a secret from a different app or environment (dev app vs production app).

Two special cases:

Webhooks you create by hand in the store admin under Settings > Notifications > Webhooks are signed with the key shown on that page, not an app secret.
If you rotate the client secret, Shopify says it can take up to an hour before digests are generated with the new secret. During that window, a check against only the new secret can fail. If you rotate, try both secrets for a while.

Also watch for invisible problems in the environment variable itself: a trailing newline from echo "secret" > .env, surrounding quotes, or a value set in one deploy environment but not another. Logging secret.length (never the secret itself) is a quick sanity check.

Cause 4: something rewrote the body before your code saw it

Proxies, API gateways and some serverless adapters can decode, re-encode or decompress the body. If the code is correct and it still fails only in production, log req.body.length next to the request's Content-Length header. If they differ, something between Shopify and your handler is changing the payload.

Use a timing-safe compare (correctly)

A plain === won't cause a mismatch, but it can leak timing information, so use crypto.timingSafeEqual. One catch: it throws if the two buffers have different lengths. A missing or garbage header would crash the handler and return a 500 instead of a 401. Check the length first.

Plain Node helper

This helper works anywhere you have the raw body as a Buffer or string:

// verify-shopify.js
const crypto = require('node:crypto');

function verifyShopifyWebhook(rawBody, hmacHeader, secret) {
  if (!hmacHeader || !secret) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody) // Buffer or string, exactly as received
    .digest();       // raw 32 bytes

  let received;
  try {
    received = Buffer.from(hmacHeader, 'base64');
  } catch {
    return false;
  }

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

module.exports = { verifyShopifyWebhook };

Comparing decoded bytes rather than base64 strings sidesteps any padding or whitespace differences in the header.

Express

Mount express.raw() on the webhook route before any global express.json(), or scope the JSON parser so it skips this path:

const express = require('express');
const { verifyShopifyWebhook } = require('./verify-shopify');

const app = express();

app.post(
  '/webhooks/shopify',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ok = verifyShopifyWebhook(
      req.body, // Buffer, thanks to express.raw
      req.get('X-Shopify-Hmac-Sha256'),
      process.env.SHOPIFY_CLIENT_SECRET
    );

    if (!ok) return res.sendStatus(401);

    // Acknowledge first, work later (see the 5-second rule below)
    res.sendStatus(200);

    const payload = JSON.parse(req.body.toString('utf8'));
    const topic = req.get('X-Shopify-Topic');
    const webhookId = req.get('X-Shopify-Webhook-Id');
    enqueue({ topic, webhookId, payload });
  }
);

// Global JSON parsing for everything else goes AFTER the webhook route
app.use(express.json());

If req.body is {} or an object inside that handler, a parser ran first. Fix the middleware order before debugging anything else.

Remix / React Router (Shopify app template)

If you built your app from Shopify's Remix or React Router template, don't hand-roll verification. authenticate.webhook() reads the raw body, checks the HMAC and throws a 401 response if it fails:

// app/routes/webhooks.jsx
import { authenticate } from '../shopify.server';

export const action = async ({ request }) => {
  const { topic, shop, payload } = await authenticate.webhook(request);

  // payload is already parsed and verified
  console.log(`Received ${topic} for ${shop}`);

  return new Response();
};

The most common mistake here is reading the body before authenticate.webhook() runs, for example calling await request.json() for logging. A Request body can only be read once. Let the library read it first.

For a Remix route without the Shopify library, read the body as text yourself and verify that:

// app/routes/webhooks.shopify.jsx
import { verifyShopifyWebhook } from '~/lib/verify-shopify.server';

export const action = async ({ request }) => {
  const rawBody = await request.text(); // read once, as-is
  const ok = verifyShopifyWebhook(
    rawBody,
    request.headers.get('X-Shopify-Hmac-Sha256'),
    process.env.SHOPIFY_CLIENT_SECRET
  );

  if (!ok) return new Response('Unauthorized', { status: 401 });

  const payload = JSON.parse(rawBody);
  // queue the work, then:
  return new Response(null, { status: 200 });
};

request.text() decodes the body as UTF-8, and Shopify sends UTF-8 JSON, so hashing the string gives the same digest as hashing the bytes. If you want to be strict, use Buffer.from(await request.arrayBuffer()) instead.

The 5-second rule

Verification isn't the only reason deliveries "fail". Shopify allows one second to connect and five seconds for the whole request. Anything other than a 2xx in that window, including a 3xx redirect, counts as a failure. Shopify retries 8 times over about 4 hours. If the subscription was created through the Admin API, it gets deleted after 8 consecutive failures.

So:

Verify the HMAC (fast, CPU only).
Return 200 right away.
Push the payload to a queue or background job for the slow work: API calls, database writes, emails.
Deduplicate using X-Shopify-Webhook-Id, because retries mean you can receive the same delivery twice.

Also make sure your endpoint doesn't redirect. A missing trailing slash or an HTTP-to-HTTPS redirect gives a 301, and Shopify counts that as a failure.

Debugging checklist

When the HMAC still doesn't match, go through these in order:

[ ] Is req.body a Buffer or string, not an object?
[ ] Are you using .digest('base64') (or comparing decoded bytes)?
[ ] Is the key the client secret of this app in this environment?
[ ] Was the webhook created in the store admin? If so, use that page's signing key.
[ ] Did you rotate the secret within the last hour?
[ ] Does the env var have a stray newline or quotes?
[ ] Does the body length match Content-Length?
[ ] Do you return a 2xx within 5 seconds, without redirects?

Fixing the first three resolves the large majority of cases.

Disclosure: I build webhook tooling; there's a short reference version of this fix at Shopify HMAC verification failed. Launch offer: code LAUNCH40 takes 40% off my webhook guide (https://6907000850732.gumroad.com/l/xunaso) until Oct 11.

Stripe webhook signature verification failed: the 5 causes and fixes

Gerald Mitchell — Fri, 09 Oct 2026 12:23:28 +0000

If you've integrated Stripe webhooks, you've probably seen this error:

StripeSignatureVerificationError: No signatures found matching the expected signature for payload.
Are you passing the raw request body you received from Stripe?

The error message is accurate but doesn't say much. Below are the five causes I see most often, in order of how common they are, with a fix for each.

How the signature works (30 seconds)

Every webhook request has a Stripe-Signature header that looks like this:

t=1728470400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Stripe computes v1 as an HMAC-SHA256 of the string "{t}.{raw_body}", keyed with your endpoint's signing secret (whsec_...). The library recomputes it on your side and compares the two. So verification only succeeds when all three of these match exactly what Stripe used:

the raw body bytes,
the signing secret,
a timestamp within the tolerance window (5 minutes by default).

Every cause below breaks one of those three.

1. Your framework parsed the body before you verified it

This causes the large majority of failures. Your framework reads the body, parses it as JSON, and hands you an object. When you pass that object (or JSON.stringify(req.body)) to constructEvent, the bytes no longer match. Key order, whitespace and unicode escaping can all change, and any change at all breaks the HMAC.

The fix is always the same: get the untouched bytes and verify those.

Express

Use express.raw() on the webhook route, and register it before any global express.json():

const express = require('express');
const Stripe = require('stripe');
const stripe = Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

// Must come before app.use(express.json())
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body, // a Buffer, thanks to express.raw()
      req.headers['stripe-signature'],
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  // handle event...
  res.sendStatus(200);
});

app.use(express.json()); // everything else gets parsed JSON

If you can't change the middleware order, keep a copy of the raw bytes with the verify hook instead:

app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf; },
}));
// then: stripe.webhooks.constructEvent(req.rawBody, sig, secret)

To check quickly, log Buffer.isBuffer(req.body) in the handler. If it prints false, the raw body has already been lost.

Next.js (App Router)

Use req.text(). Don't use req.json():

// app/api/webhook/route.js
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function POST(req) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature');
  try {
    const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET);
    // handle event...
    return new Response('ok', { status: 200 });
  } catch (err) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }
}

Next.js (Pages Router)

Turn off the built-in body parser and read the stream yourself:

// pages/api/webhook.js
export const config = { api: { bodyParser: false } };

async function readRaw(req) {
  const chunks = [];
  for await (const chunk of req) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
  return Buffer.concat(chunks);
}

export default async function handler(req, res) {
  const buf = await readRaw(req);
  const event = stripe.webhooks.constructEvent(
    buf, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  res.status(200).end();
}

NestJS

Enable raw body support when you create the app, then read req.rawBody:

const app = await NestFactory.create(AppModule, { rawBody: true });

// in the controller
@Post('webhook')
handle(@Req() req: RawBodyRequest<Request>, @Headers('stripe-signature') sig: string) {
  const event = this.stripe.webhooks.constructEvent(req.rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET);
}

Fastify

Tell Fastify to give you a Buffer for JSON:

fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => {
  done(null, body);
});
// request.body is now a Buffer; parse it yourself after verifying

(Scope this to the webhook route with a plugin if other routes need parsed JSON.)

Flask

@app.post("/webhook")
def webhook():
    payload = request.get_data()  # raw bytes. Don't use request.json
    sig = request.headers.get("Stripe-Signature")
    event = stripe.Webhook.construct_event(payload, sig, os.environ["STRIPE_WEBHOOK_SECRET"])
    return "", 200

Cloudflare Workers / edge runtimes

There's no Node crypto here, so use the async variant with the Web Crypto provider:

const stripe = new Stripe(env.STRIPE_SECRET_KEY, { httpClient: Stripe.createFetchHttpClient() });
const body = await request.text();
const event = await stripe.webhooks.constructEventAsync(
  body,
  request.headers.get('stripe-signature'),
  env.STRIPE_WEBHOOK_SECRET,
  undefined,
  Stripe.createSubtleCryptoProvider()
);

2. You're using the wrong secret

The secret you pass must be the endpoint signing secret:

It starts with whsec_. An sk_live_, sk_test_, rk_ or pk_ key will never verify a webhook.
Each endpoint has its own secret. If you have a staging endpoint and a production endpoint, they don't share one. Copy it from Developers → Webhooks → your endpoint → Signing secret.
The Stripe CLI uses its own secret. stripe listen --forward-to localhost:3000/webhook prints a whsec_... that's different from the dashboard one. Locally you need the CLI value; in production you need the dashboard value.
If you rolled the secret, the old one stops working once its expiry passes. Redeploy with the new one.

Also check for stray whitespace or quotes when the secret comes from an .env file or a CI variable. A trailing newline is enough to break it. A cheap guard:

const secret = process.env.STRIPE_WEBHOOK_SECRET?.trim();
if (!secret?.startsWith('whsec_')) throw new Error('STRIPE_WEBHOOK_SECRET looks wrong');

3. Test mode vs. live mode

Test mode and live mode endpoints are separate objects with separate secrets. If your production server receives live events but has the test-mode whsec_ (or the other way around), every single event fails, even though nothing looks wrong. Check event.livemode in a few successful test events, and keep the two secrets in clearly named variables (STRIPE_WEBHOOK_SECRET_LIVE / _TEST) so they can't get swapped silently.

4. Something modified the body in transit

Your code may be fine, but something in front of it changes the request:

A reverse proxy or API gateway that re-encodes the body, or adds or removes a trailing newline.
Logging or tracing middleware that reads the stream and re-serializes it.
Serverless platforms that base64-encode the body (AWS API Gateway with isBase64Encoded: true). Decode it back to bytes before you verify.
Converting the body with the wrong encoding, e.g. buf.toString('latin1'). If you convert it to a string, use UTF-8, or just pass the Buffer.

Rule of thumb: verify as early as possible and as close to the socket as possible, then parse.

5. The timestamp is too old

By default the libraries reject a signature whose t= is more than 300 seconds away from your server's clock. This shows up as Timestamp outside the tolerance zone. Common reasons:

Your server or container clock has drifted. Make sure NTP is running.
You put the raw webhook on a queue and verify it later. Verify when it arrives, then queue the parsed event.
You're replaying an old payload you saved during debugging.

You can pass a larger tolerance as the fourth argument (constructEvent(body, sig, secret, 600)), but the window is there to stop replayed requests, so fix the clock before you widen it.

After it verifies: don't lose events

Getting the signature to pass is half the job. A few habits that prevent the next round of bugs:

Return 2xx fast. Acknowledge the event, then do the slow work (emails, DB writes, API calls) in the background. Stripe treats slow responses as failures and retries them.
Be idempotent. Stripe can deliver the same event more than once. Store event.id and skip events you've already processed.
Don't count on ordering. invoice.paid can arrive before customer.subscription.updated. Fetch the current object from the API if order matters.
Plan for downtime. Live-mode retries stop after about 3 days. If your endpoint is down longer than that, or keeps erroring, those events are gone. You can recover them from the Events API, but having something that stores events and retries them for you is much nicer.

Quick debugging checklist

Is the thing you pass to constructEvent a Buffer or string of the exact request bytes?
Does the secret start with whsec_, and is it for this endpoint and this mode?
Locally, are you using the stripe listen secret?
Is anything between Stripe and your handler touching the body?
Is your server clock correct?

If those five check out, the signature will verify.

The full write-up with more framework fixes is the Fix Your Stripe Webhooks guide ($9). I also open-sourced the relay I use to store and retry events: webhook-relay. I'm the author of both.