hooks.bot Docs / Shopify

Shopify webhook signature verification

Shopify signs each webhook and sends the digest in X-Shopify-Hmac-Sha256. When your check fails, one of a small number of steps is wrong — and guessing which is the slow way to find out. Paste the payload, the secret and the header block into the debugger and it rebuilds the signature every way it could plausibly have been made, then names the step that differs. It runs in your browser: the secret never leaves the page.

The scheme

Exactly what Shopify signs

Field	Value
Header	`X-Shopify-Hmac-Sha256`
Signed string	`raw body`
Algorithm	HMAC-SHA-256
Digest encoding	base64
Key	Your app's client secret (API secret key) — not the API key, not an access token.
Replay window	not timestamped

Official reference: https://shopify.dev/docs/apps/build/webhooks/subscribe/https#verify-the-webhook.

Causes

What actually goes wrong

Your framework parsed the body before you verified it. The signature covers the bytes on the wire. Once JSON has been parsed and re-serialized, whitespace and number formatting shift and the HMAC no longer matches. Read the raw body first: await req.text() in Next.js and Workers, express.raw() mounted before any express.json(), await request.body() in FastAPI, $request->getContent() in Laravel.
Whitespace on the secret. A trailing newline from a .env file or a Docker secret mounted as a file changes the key and nothing else. The debugger names this one specifically.
The wrong credential entirely. Shopify issues several, and a Shopify admin API access token, a Shopify custom app access token or a Shopify shared secret from a different app will all fail here. The debugger recognises each by its prefix and says so before it tries anything else.
The wrong key derivation. Your app's client secret (API secret key) — not the API key, not an access token.

Stripe and Svix both issue secrets that begin whsec_ and derive keys from them completely differently. Stripe uses the whole string, prefix included. Svix and Standard Webhooks strip the prefix and base64-decode the rest. This is the single commonest failure in the category.

Capture it

Get the real bytes, not a copy of a copy

If you are diagnosing from a logged payload you may be debugging the log rather than the webhook. Point Shopify at a disposable URL and work from what actually arrived:

curl -X POST https://www.hooks.bot/api/endpoints
# {"url":"https://www.hooks.bot/h/abc…"}

Paste that URL into your Shopify webhook settings, trigger an event, and the request appears at https://www.hooks.bot the moment it lands — headers, body and all. Press Diagnose this signature and add your secret.

Or let your agent do it

claude mcp add --transport http hooks-bot https://www.hooks.bot/mcp

Claude Code, Cursor and Codex can create the endpoint, block until the webhook lands, and diagnose it against the captured bytes without you copying anything.

Other providers

Stripe · GitHub · Svix / Standard Webhooks · Slack · Paddle Billing · Twilio