Test Shopify Webhooks Locally

From a stuck handler to a live Shopify delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL — something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3App-specific webhooks: put a relative uri = "/webhooks" in shopify.app.toml and let the CLI point it at your tunnel. For shop-specific or admin webhooks, register the full URL — https://your-app-12.localcan.dev/webhooks — via the Admin API webhookSubscriptionCreate, or in the merchant admin under Settings → Notifications → Webhooks. Because the LocalCan URL is fixed, you can hardcode it once instead of chasing a rotating tunnel.
4. 4Fire one with shopify app webhook trigger --topic=orders/create --address=https://your-app-12.localcan.dev/webhooks --client-secret=shpss_... --delivery-method=http. You pass --client-secret so the CLI can sign a valid X-Shopify-Hmac-SHA256. For admin-created webhooks, use Settings → Notifications → Webhooks → ⋯ → Send test. Note: there is no per-delivery Replay button in Shopify — you re-trigger, or you hit Replay in LocalCan.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body — expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

X-Shopify-Hmac-SHA256

Algorithm

HMAC-SHA256, base64-encoded

What's signed

Shopify signs the RAW request body bytes only — no timestamp prefix, no versioned signing string. You compute base64(HMAC-SHA256(rawBody, clientSecret)) and compare it, timing-safe, against the X-Shopify-Hmac-SHA256 header. Parse the JSON before reading the raw body, or compare against a hex digest, and it can never match.

Secret

The signing key is your app’s CLIENT SECRET (a.k.a. API secret key / shared secret), found in the Partner/Dev Dashboard under Apps → your app → client credentials. It is one per-app secret — not a per-endpoint secret — so the same shpss_… signs every webhook. Newer secrets are 38 chars with a static shpss_ prefix; older ones were 32 chars with no prefix. After rotating it, Shopify can take up to an hour to start signing with the new secret, so verification may transiently fail during that window.

import express from 'express'
import crypto from 'crypto'

const clientSecret = process.env.SHOPIFY_API_SECRET // shpss_...

const app = express()

// Shopify signs the RAW bytes — mount express.raw BEFORE any JSON parser.
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Shopify-Hmac-SHA256') || ''

  // base64(HMAC-SHA256(rawBody, clientSecret)) — NOT hex.
  const digest = crypto
    .createHmac('sha256', clientSecret)
    .update(req.body) // req.body is a Buffer of the raw bytes
    .digest('base64')

  // Compare the decoded base64 values, length-checked, in constant time.
  const a = Buffer.from(header, 'base64')
  const b = Buffer.from(digest, 'base64')
  const ok = a.length === b.length && crypto.timingSafeEqual(a, b)

  if (!ok) {
    return res.status(401).send('HMAC verification failed')
  }

  // Return 200 within 5s — enqueue heavy work, do not block on it.
  const topic = req.get('X-Shopify-Topic')
  if (topic === 'orders/create') {
    // handle it asynchronously
  }
  res.sendStatus(200)
})