DEV Community: Gerald Mitchell

Clean an email list before you hit send: syntax, MX, disposable and role checks in Python

Gerald Mitchell — Sat, 24 Oct 2026 06:28:59 +0000

High bounce rates get your sending domain throttled or blocked. Most bad addresses fall into four buckets you can catch locally, for free, before sending anything.

Check	Catches	Cost
Syntax	`john@@gmail`, `jane@gmail,com`	instant
Typo domains	`gmial.com`, `hotnail.com`	instant
MX lookup	domains that can't receive mail	1 DNS query/domain
Disposable / role	`mailinator.com`, `info@`, `noreply@`	instant

Setup

pip install dnspython "email-validator>=2"

The script

import csv, sys
from functools import lru_cache
import dns.resolver
from email_validator import validate_email, EmailNotValidError

DISPOSABLE = {"mailinator.com", "10minutemail.com", "guerrillamail.com", "yopmail.com", "tempmail.com"}
ROLE = {"info", "admin", "support", "sales", "noreply", "no-reply", "contact", "office", "webmaster"}
TYPOS = {"gmial.com": "gmail.com", "gamil.com": "gmail.com", "hotnail.com": "hotmail.com", "yaho.com": "yahoo.com"}

@lru_cache(maxsize=None)
def has_mx(domain):
    try:
        return bool(dns.resolver.resolve(domain, "MX", lifetime=5))
    except Exception:
        return False

def check(addr):
    addr = addr.strip().lower()
    try:
        addr = validate_email(addr, check_deliverability=False).normalized
    except EmailNotValidError:
        return addr, "invalid_syntax"
    local, domain = addr.rsplit("@", 1)
    if domain in TYPOS:      return addr, f"typo->{TYPOS[domain]}"
    if domain in DISPOSABLE: return addr, "disposable"
    if local in ROLE:        return addr, "role"
    if not has_mx(domain):   return addr, "no_mx"
    return addr, "ok"

rows = list(csv.DictReader(open(sys.argv[1], newline="")))
seen = set()
with open("cleaned.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=list(rows[0].keys()) + ["status"])
    w.writeheader()
    for r in rows:
        email, status = check(r["email"])
        if email in seen: status = "duplicate"
        seen.add(email)
        w.writerow({**r, "email": email, "status": status})
print("wrote cleaned.csv")

Run it with python clean.py contacts.csv and filter on status == ok.

Notes

Cache MX lookups per domain (done above with lru_cache). 10,000 emails often share fewer than 500 domains.
Don't "verify" by opening SMTP connections to every mailbox; many providers treat that as abuse and may blocklist your IP.
Role addresses aren't invalid, just low-engagement; decide per campaign.
Real disposable lists have thousands of domains; refresh yours from a maintained public list.

Disclosure: I drafted this article with help from an AI assistant and checked the code and claims by hand.

If you want this ready-made with a maintained disposable-domain list, typo correction, parallel DNS, and a summary report, it's packaged as Email List Cleaner Pro ($9), a single CLI that runs offline except for DNS.

Independent write-up by the author; not affiliated with or endorsed by Stripe, Shopify, GitHub, Gumroad or any other vendor mentioned.

Verify webhook signatures correctly: Stripe, Shopify and GitHub side by side

Gerald Mitchell — Sat, 24 Oct 2026 06:28:28 +0000

Every major provider signs webhooks with HMAC, and almost every integration bug comes from the same three mistakes: hashing a re-serialized body, comparing strings unsafely, and processing the same event twice.

1. Hash the raw bytes, never parsed JSON

JSON.parse → JSON.stringify changes whitespace and key order, so the HMAC won't match. Capture the raw body before any JSON middleware.

// Express: mount this BEFORE app.use(express.json())
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), handler);

Next.js App Router: use await req.text(), not req.json().

2. Each provider, one function

import crypto from "node:crypto";
const safeEq = (a, b) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));

// Stripe: header "t=...,v1=..."; signed payload = `${t}.${raw}`, hex
export function stripe(raw, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const sig = crypto.createHmac("sha256", secret).update(`${parts.t}.${raw}`).digest("hex");
  return safeEq(sig, parts.v1); // Stripe may send several v1= values during secret rotation; accept if any matches.
}

// Shopify: X-Shopify-Hmac-Sha256, base64 of HMAC over raw body
export const shopify = (raw, h, secret) =>
  safeEq(crypto.createHmac("sha256", secret).update(raw).digest("base64"), h);

// GitHub: X-Hub-Signature-256 = "sha256=" + hex
export const github = (raw, h, secret) =>
  safeEq("sha256=" + crypto.createHmac("sha256", secret).update(raw).digest("hex"), h);

In production prefer the official SDK where one exists (stripe.webhooks.constructEvent), but knowing the shape helps you debug it.

3. Use a timing-safe comparison

sig === header leaks how many leading characters matched. crypto.timingSafeEqual (Node), hmac.compare_digest (Python) and subtle.ConstantTimeCompare (Go) don't. Check lengths first; timingSafeEqual throws on unequal lengths.

4. Reject replays

Stripe includes a timestamp in the signed payload, so enforce a window (5 minutes is the SDK default). For providers without one, rely on step 5.

5. Be idempotent

Providers retry on timeouts, so you will receive duplicates.

CREATE TABLE processed_events (id text PRIMARY KEY, received_at timestamptz DEFAULT now());
-- INSERT ... ON CONFLICT DO NOTHING; only act if a row was inserted

Respond 2xx fast and move slow work to a queue, or the provider will time out and retry anyway.

Debug checklist

Using the endpoint's signing secret (whsec_...), not your API key?
Test-mode vs live-mode secret mixed up?
A proxy (Cloudflare, API Gateway) modifying or re-encoding the body?
Body read as a UTF-8 string when it contained non-UTF-8 bytes? Hash the Buffer.

Disclosure: I drafted this article with help from an AI assistant and checked the code and claims by hand.

I keep a one-page Webhook Signature Cheat Sheet (free) with the header names, encodings and gotchas for each provider. If you want the whole toolchain (a self-hosted relay that verifies and retries, AI coding-assistant skills for webhook work, and the CORS kit), there's a Webhook & CORS Fix Bundle.

Independent write-up by the author; not affiliated with or endorsed by Stripe, Shopify, GitHub, Gumroad or any other vendor mentioned.

Fixing "No 'Access-Control-Allow-Origin' header": a 5-minute CORS checklist

Gerald Mitchell — Sat, 24 Oct 2026 06:28:09 +0000

You call your API from the frontend and the console shows:

Access to fetch at 'https://api.example.com/data' from origin 'http://localhost:5173'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
on the requested resource.

The request often reached your server and succeeded. The browser just refused to hand the response to your JavaScript. CORS is enforced by the browser, so the fix almost always lives on the server, not in the fetch call.

Step 1: Is it a preflight?

The browser sends an OPTIONS request first if any of these are true:

the method isn't GET, HEAD or POST
you send a Content-Type other than text/plain, multipart/form-data or application/x-www-form-urlencoded (e.g. application/json)
you send custom headers such as Authorization

Open DevTools > Network, tick "All", and look for an OPTIONS request. If it returns 404, 401 or 405, that is your bug: your router or auth middleware rejects OPTIONS before CORS headers are added.

Step 2: Check the four headers

Header	Needed when
`Access-Control-Allow-Origin`	always; exact origin, or `*`
`Access-Control-Allow-Methods`	preflight
`Access-Control-Allow-Headers`	preflight with custom headers
`Access-Control-Allow-Credentials: true`	cookies / `credentials: 'include'`

You can test without a browser:

curl -i -X OPTIONS https://api.example.com/data \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type,authorization"

Step 3: The classic gotchas

* with credentials. Allow-Origin: * is ignored when the request carries cookies. Echo the specific origin and add Vary: Origin.
Trailing slash or port mismatch. http://localhost:5173 ≠ http://localhost:5173/ ≠ http://127.0.0.1:5173.
Headers only on success. Your 500 error page has no CORS headers, so a server crash looks like a CORS error. Check the server log.
Duplicate headers. Nginx and the app both add Allow-Origin; browsers reject two values.
Auth before CORS. Move CORS middleware above auth so OPTIONS gets answered.

Copy-paste fixes

Express

import cors from "cors";
app.use(cors({ origin: ["http://localhost:5173", "https://app.example.com"], credentials: true }));

Next.js route handler

const H = { "Access-Control-Allow-Origin": "https://app.example.com",
  "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization" };
export async function OPTIONS() { return new Response(null, { status: 204, headers: H }); }
export async function POST(req) { return Response.json({ ok: true }, { headers: H }); }

Flask

from flask_cors import CORS
CORS(app, origins=["https://app.example.com"], supports_credentials=True)

FastAPI

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"],
    allow_credentials=True, allow_methods=["*"], allow_headers=["*"])

Nginx

location /api/ {
  if ($request_method = OPTIONS) {
    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;
    add_header Access-Control-Allow-Credentials true always;
    return 204;
  }
  add_header Access-Control-Allow-Origin $http_origin always;
  add_header Vary Origin always;
  proxy_pass http://app;
}

(Use a map allowlist instead of blindly echoing $http_origin in production.)

Dev-only shortcut: a proxy

In Vite, server.proxy = { '/api': 'http://localhost:3000' } makes the request same-origin, so CORS never applies locally.

Disclosure: I drafted this article with help from an AI assistant and checked the code and claims by hand.

If you'd rather not walk through this by hand every time, I packaged a small diagnosis script plus tested configs for 10+ frameworks as the CORS Fix Kit ($9). The checklist above is free to use either way.

Independent write-up by the author; not affiliated with or endorsed by Stripe, Shopify, GitHub, Gumroad or any other vendor mentioned.

Why your CORS preflight fails even with the right headers (redirects, wildcards, credentials)

Gerald Mitchell — Fri, 23 Oct 2026 15:13:59 +0000

Disclosure: the fix pages linked here are ours (free, no signup). This article was written with AI assistance and reviewed by us. Not affiliated with any vendor mentioned.

You added Access-Control-Allow-Origin, the methods, the headers. curl works, Postman works, and the browser still says the preflight failed. Here are the three cases we see most where "more headers" won't help, with a curl check for each.

First, the one command that tells you most of what you need. It sends the same OPTIONS preflight the browser sends:

curl -si -X OPTIONS https://api.example.com/api/items \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type,authorization"

Look at the status line first, then the access-control-* headers.

1. "Redirect is not allowed for a preflight request"

If the status is 301, 302, 307 or 308, that's your bug. Browsers don't follow redirects on a preflight, so no CORS header fixes it. The usual causes:

calling http:// when the API redirects to https://
a trailing-slash redirect, /api/items to /api/items/ (Django APPEND_SLASH, FastAPI redirect_slashes, Next.js trailingSlash)
apex to www, or a login redirect on OPTIONS

Fix: call the exact final URL from your front end (same scheme, host and trailing slash as the Location header). If it's a login redirect, exempt OPTIONS from auth.

2. "It does not have HTTP ok status"

The preflight returned 401, 403, 404, 405 or 500. Preflights never carry cookies or the Authorization header, so auth middleware rejects them, or the router has no OPTIONS handler for that path.

Fix: answer OPTIONS with a 204 before authentication, CSRF and routing:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 600
Vary: Origin

3. Wildcard with credentials

If you use fetch(url, { credentials: 'include' }) or axios withCredentials: true, the browser rejects Access-Control-Allow-Origin: *. With credentials, * in Allow-Headers and Allow-Methods is also treated literally, and * never covers Authorization anyway.

Fix: echo the request's Origin only if it's on your allowlist, and add credentials and Vary:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin

Express: cors({ origin: ['https://app.example.com'], credentials: true })
FastAPI: allow_origins=[...] (not ["*"]) with allow_credentials=True

Don't reflect every Origin blindly. With credentials, that lets any website read your users' authenticated responses. Cross-site cookies also need SameSite=None; Secure.

Bonus: errors that skip your middleware

"No 'Access-Control-Allow-Origin' header is present" often means the request actually failed (a 401, 404 or 500 from an error handler that runs outside your CORS middleware) or a proxy stripped the header. In nginx, use add_header ... always; so 4xx/5xx responses get the header too. In Express, mount the CORS middleware before all routes.

More fixes

We keep a free page for each of these messages, plus the Allow-Headers and Allow-Methods errors: CORS error fixes.

If you'd rather not hand-write this per stack, our $9 CORS Fix Kit includes the cors-doctor CLI, which sends a real preflight and names the wrong header, plus tested configs for 13 stacks.

How to Clean an Email List Locally with a Free Open-Source Node CLI

Gerald Mitchell — Thu, 22 Oct 2026 21:55:23 +0000

Disclosure: we built and maintain the tool in this post (email-list-cleaner, MIT). This article was written with AI assistance and reviewed by us.

Bounces hurt sender reputation, and many "list verification" services require uploading your contacts to a third party. If you just need to catch the obvious problems, you can do it on your own machine with a zero-dependency Node.js CLI.

Repo: https://github.com/5012763083a-oss/email-list-cleaner

What it checks

Syntax: is the address well-formed?
MX lookup: does the domain publish mail servers? Public DNS only, with no SMTP probing, so no mail server is contacted.
Disposable domains: flags throwaway inbox providers.
Role accounts: flags info@, admin@, support@ and similar addresses.
Typos: suggests fixes like gmial.com → gmail.com.
Duplicates: removed case-insensitively.

Nothing in your list leaves your machine. The only network traffic is DNS lookups for the domains.

Usage

Run it straight from GitHub with npx (Node required):

npx github:5012763083a-oss/email-list-cleaner contacts.csv -o cleaned.csv

Options:

--column email   # which CSV column holds the address
--no-mx          # skip DNS lookups (fully offline)
--no-dedupe      # keep duplicates

For example, if your export has the address in a Email Address column and you're offline:

npx github:5012763083a-oss/email-list-cleaner export.csv --column "Email Address" --no-mx -o cleaned.csv

Reading the output

Your original columns are kept, and these are appended:

normalized,status,reason,syntaxValid,domain,hasMx,mxHosts,isDisposable,isRoleAccount,isFreeProvider,didYouMean

status is one of valid, invalid, risky or unknown. A practical workflow:

Drop invalid rows (bad syntax or no MX).
Review risky rows: disposable or role addresses may be fine for a B2B list but not for a newsletter.
Check didYouMean: fixing jane@gmial.com recovers a real subscriber instead of losing them.
unknown usually means a DNS lookup failed; rerun later. It's also the status you get for every address with --no-mx, with the reason mx_not_checked.

Open cleaned.csv in a spreadsheet and filter by status.

Limits

MX checks tell you a domain can receive mail, not that a specific mailbox exists. That's deliberate: confirming mailboxes requires SMTP probing, which is slow and can get your IP flagged. For most list hygiene, syntax + MX + disposable + typo checks catch the bulk of bad addresses.

The free edition processes the first 500 rows per file. It's MIT-licensed, so you can fork it and change FREE_LIMIT in bin/email-clean.js.

Run the tests with npm test.

If you'd rather support the project, Email List Cleaner Pro ($9) removes the cap and adds batch mode and a summary report: https://6907000850732.gumroad.com/l/khnxbj?ref=devto

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.