Answers from our docs and articlesesc to close
Try asking
Create an accountSign up

Verifying Shopify webhook HMACs: raw bodies and timing-safe compare

How Shopify signs webhooks, the four bugs that break verification (parsed bodies, string compare, wrong secret, body limits) and a correct Node check.

Key takeaways

  • Shopify signs every webhook with X-Shopify-Hmac-Sha256: the base64 HMAC-SHA256 of the raw request body, keyed with the app's client secret.
  • Most failed checks come from four bugs: verifying a body that was already parsed, comparing strings with ===, using another environment's secret, and a body-size limit that refuses large payloads.
  • Verify the exact bytes, decode the header to bytes, check the lengths, then use timingSafeEqual, and only parse the JSON after that.
  • On Apps, Inference Bureau checks each delivery against that environment's own client secret, refuses bad or oversized ones with a 401, and drops a repeated webhook id before your code runs.

Our guide to hosting a Shopify app gives the rule in one line: verify the HMAC on the raw bytes, then compare in constant time. Getting either part slightly wrong is a common bug, and it usually shows up the same way: deliveries fail with a 401 or a 413, and Shopify keeps retrying them.

What Shopify signs

Every HTTPS delivery carries eight headers, per Shopify's delivery docs (read 2026-10-23): X-Shopify-Topic, X-Shopify-Hmac-Sha256, X-Shopify-Shop-Domain, X-Shopify-API-Version, X-Shopify-Webhook-Id, X-Shopify-Triggered-At, X-Shopify-Event-Id and, when the subscription has a name, X-Shopify-Name. Shopify's pages spell the HMAC header both Sha256 and SHA256; header names are case-insensitive.

The HMAC header is the base64-encoded HMAC-SHA256 of the request body, keyed with the app's client secret. Only the body is signed, so read the topic and shop headers only after the check passes.

Shopify allows one second to connect and five seconds for the whole request. Anything outside the 2xx range counts as a failure, and a failed delivery is retried 8 times over the next 4 hours. After 8 failures in a row, a subscription created through the Admin API is deleted. So a broken check can end the subscription, not just lose a few events.

Bug 1: verifying a parsed body

The HMAC covers bytes, not JSON values. If a body parser runs first and you call JSON.stringify(req.body) to verify, the bytes change. Whitespace goes, key order can shift, \u0026 becomes &, and a number such as 10.50 comes back as 10.5. The check then fails on some payloads and passes on others.

In Express, mount express.raw({ type: "application/json" }) on the webhook route instead of express.json(). In a Next.js route handler, read await request.arrayBuffer(), not request.json().

Bug 2: comparing with ===

computed === header stops at the first character that differs, so the response time reveals how much of a guess was right. Use crypto.timingSafeEqual. It has two traps of its own: it throws when the two buffers differ in length, and it compares bytes, so a hex digest against a base64 header never matches. Decode the header from base64 and compare it with the raw digest.

Bug 3: the wrong secret for the environment

Development and production are normally separate Shopify apps, each with its own client secret. A production server holding development's secret rejects every delivery, yet works in local testing. Load the secret alongside the client ID it belongs to.

Rotation needs care as well. Shopify says a rotated secret can take up to an hour to be used for signing. During that hour, accept a signature from either the old or the new secret, then remove the old one.

Bug 4: body limits

Express's body parsers refuse bodies over 100 KB by default. A large order or product payload gets a 413, Shopify retries it 8 times, and the subscription can be deleted. Set an explicit limit on the webhook route that's above what your topics send, and check Content-Length before you buffer a body bigger than that.

A correct check in Node

import { createHmac, timingSafeEqual } from "node:crypto";

const MAX_BYTES = 1024 * 1024;

export function verifyShopifyWebhook(raw: Buffer, header: string | null, secret: string): boolean {
  if (!header) return false;
  const expected = createHmac("sha256", secret).update(raw).digest();
  const given = Buffer.from(header, "base64");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

// app/webhooks/shopify/route.ts (Next.js App Router)
export async function POST(request: Request) {
  if (Number(request.headers.get("content-length") ?? 0) > MAX_BYTES) return new Response(null, { status: 413 });
  const raw = Buffer.from(await request.arrayBuffer());
  const ok = verifyShopifyWebhook(raw, request.headers.get("x-shopify-hmac-sha256"), process.env.SHOPIFY_API_SECRET!);
  if (!ok) return new Response(null, { status: 401 });

  const webhookId = request.headers.get("x-shopify-webhook-id");
  // Skip a webhookId you've already handled, queue the work, then answer.
  const payload = JSON.parse(raw.toString("utf8"));
  return new Response(null, { status: 200 });
}

A valid signature doesn't mean a new event: Shopify redelivers, so key idempotency on X-Shopify-Webhook-Id. X-Shopify-Event-Id is a different id: it is shared by every subscription's delivery of the same change, so use it to link those deliveries to each other.

How Apps does it

On Apps, Shopify posts to a webhook URL that names the environment. Inference Bureau reads the body as text, refuses it with a 401 if it's over 1 MiB or its X-Shopify-Hmac-Sha256 doesn't match, and parses the JSON only after the check. The key is that environment's own client secret, since each environment has its own Shopify app. The secret never reaches your app's code.

After the check:

  • Repeats are dropped. A webhook id already received in that environment in the last three days is answered and not handled again. A job queued from a webhook also carries the id as its dedupe key.
  • Your code runs after the answer. A topic listed in settings.ib.ts queues its action as a job, and Shopify gets its 200 once the job is queued. Synced models and the privacy topics are written after the answer too.
  • Logs keep metadata, not the payload. Each delivery's event records the shop, webhook id, API version and size, because payloads can hold customer data.

Frequently asked questions

Which secret signs Shopify webhooks?

The app's client secret, also called the API secret key. Each Shopify app has its own, so development and production apps sign with different secrets.

Why does my HMAC check fail only on some webhooks?

Usually because the body was parsed and re-serialized before the check. Escapes, number formats and whitespace change, so some payloads still match and others don't. Verify the raw bytes.

Is X-Shopify-Hmac-Sha256 hex or base64?

Base64. Decode it and compare it with the raw HMAC-SHA256 digest using a constant-time compare, after checking that both are the same length.

Do I need to verify webhooks on Apps?

No. Inference Bureau checks every delivery with the environment's client secret before your code runs, refuses bad or oversized ones with a 401, and drops repeated webhook ids.

One bill for your apps, your models and your reviews.

Host apps and functions next to your model traffic. Routing picks each turn's model by your quality floor, and Auditor reviews every pull request against your own rules.