Shopify HMAC Verification Failed

Verified Shopify HMAC facts

Shopify documents X-Shopify-Hmac-SHA256 as a base64 HMAC over the raw request body using the app client secret Shopify HMAC docs.

First five minutes

• Do not log the real secret or full HMAC value.
• Record the delivery ID, shop domain, topic, timestamp, and whether the failure occurred at Shopify inbound or Webhook Guard downstream authentication.
• Confirm the secret source, environment, and recent rotation history.
• Check whether middleware parsed, reserialized, or transformed the body before verification.
• Preserve a sanitized failure sample with headers and payload length.

Evidence to collect

Focused failure-stage map

Fast decision tree

1. Is the failure for Shopify inbound verification or Webhook Guard downstream API-key authentication? Diagnose the correct trust boundary first.
2. Was the HMAC computed from raw request bytes? If no, fix body capture before investigating secrets.
3. Does the runtime secret match the Shopify app secret for this environment? If no, fix configuration and rotation process.
4. Was the app secret rotated recently? If yes, allow for documented propagation behavior and accept both expected secrets only when your security process explicitly supports it.
5. If raw body and secret are correct, inspect proxy, framework, encoding, base64 decoding, and constant-time comparison behavior.

Root-cause matrix

Raw body handling

Secret configuration

Detailed diagnostic procedure

1. Confirm the exact inbound path and whether Webhook Guard or your endpoint is performing Shopify HMAC verification.
2. Inspect framework middleware order and ensure the verifier receives the raw request body before JSON parsing.
3. Check that the header lookup is case-insensitive and reads X-Shopify-Hmac-Sha256.
4. Compare decoded base64 buffers with a constant-time comparison after checking lengths.
5. If a proxy sits in front of the app, confirm it does not decompress, rewrite, or normalize the body before the app receives it.

Immediate containment

• Do not bypass HMAC verification in production.
• Stop printing secrets, full signatures, or unsanitized payloads in logs.
• Keep invalid requests blocked while you test with a known Shopify delivery.

Permanent fix

• Add route-specific raw-body handling for Shopify webhooks.
• Add secret rotation runbooks and environment checks.
• Add tests that fail if middleware order changes and HMAC verification uses parsed JSON.

Architecture improvement

• Keep authentication, durable recording, and parsing as separate steps.
• Mask secrets and sensitive headers in every log view.
• Track invalid-signature counts separately from downstream delivery failures.

Safe recovery gate

What Webhook Guard can and cannot prove

Can show

• Invalid events that failed signature validation before forwarding.
• Headers and metadata useful for investigating the failing request, with sensitive values protected by the product UI.

Cannot prove

• It cannot validate your customer endpoint's separate authentication logic unless that endpoint reports its result.
• It cannot make a parsed request body equivalent to the raw bytes Shopify signed.

Webhook Guard evidence for this incident

Safe Node.js Verification Shape

This example shows the important boundary: verify the raw request body before parsing it Shopify HMAC docs. Keep real secrets out of logs.

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

function verifyShopifyWebhook(rawBody, hmacHeader, secret) {
  const digest = createHmac("sha256", secret).update(rawBody).digest()
  const received = Buffer.from(hmacHeader, "base64")

  if (digest.length !== received.length) return false
  return timingSafeEqual(digest, received)
}

Production runbook

1. Identify the trust boundary.
2. Verify raw-body capture.
3. Verify secret and rotation state.
4. Check encoding and comparison.
5. Retest with one controlled delivery.

Related playbooks and concepts

Sources and last verification