DEV Community: Prateek Jain

Why Shopify Webhook HMAC Verification Keeps Failing

Prateek Jain — Fri, 06 Mar 2026 15:58:26 +0000

You set up the webhook. Got the secret. Wrote the HMAC check. Still getting:

HMAC VALIDATION FAILED

Or worse — it passes locally but fails Shopify's automated review. Here's every real reason it happens.

if you just want all of this handled without thinking about it — Tern fixes every issue below out of the box. keep reading to understand why.

1. You're using the wrong secret

This is the most common one and it's not obvious from the docs.

Shopify doesn't give you a dedicated webhook secret like Stripe does. You use your app's client secret — the API secret key from your Partner Dashboard. Not the API key. Not the access token. The client secret.

# ❌ wrong — this is the API key
SHOPIFY_API_KEY=abc123...

# ✅ correct — this is what signs webhooks
SHOPIFY_API_SECRET=shpss_xyz789...

If you're passing the wrong value here every HMAC will fail silently.

2. The signature is base64 — not hex

Shopify's X-Shopify-Hmac-SHA256 header is base64 encoded, not hex like Stripe.

Most HMAC examples online use .digest('hex'). That gives you the wrong output for Shopify.

// ❌ wrong encoding — hex output won't match
const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex')

// ✅ correct — base64 to match Shopify's header
const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('base64')

One word difference. Hours of debugging.

3. Raw body getting parsed before verification

Same problem as Stripe but Shopify's error message gives you even less to go on.

Your framework parses the body into a JavaScript object before your handler runs. You re-stringify it. The whitespace changes. The signature doesn't match.

// ❌ body is already a parsed object here
app.use(express.json())

app.post('/webhook', (req, res) => {
  const body = JSON.stringify(req.body) // not the original bytes
  // verification fails
})

Fix — raw body parser specifically for the webhook route:

// ✅raw bytes preserved
app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const hmac = req.headers['x-shopify-hmac-sha256']
    const signature = crypto
      .createHmac('sha256', process.env.SHOPIFY_API_SECRET)
      .update(req.body) // Buffer, not parsed object
      .digest('base64')

    if (signature !== hmac) return res.status(401).send('Unauthorized')
    res.status(200).send('OK')
  }
)

4. Shopify's automated review check failing

You test manually, everything works. You submit for app review, the HMAC check fails.

This happens because Shopify's automated checker sends GDPR compliance webhooks — not regular order or product events. If your handler only handles specific topics and ignores GDPR webhooks, the check fails.

Make sure your handler responds correctly to:

customers/data_request
customers/redact
shop/redact

These are mandatory. If they return anything other than 200, the HMAC check is marked as failed even if your signature logic is correct.

5. Body consumed before your route runs

In Remix and some other frameworks, the authentication middleware reads the request body first. By the time your webhook handler runs, the stream is already consumed.

Fix — clone the request before anything touches it:

const reqClone = request.clone()
const rawPayload = await reqClone.text()
// use rawPayload for HMAC verification

The pattern underneath all of this

Shopify webhook failures almost always come down to wrong secret, wrong encoding, or body consumed before verification. The HMAC logic itself is not complicated. The plumbing around it is where everything breaks.

How Tern handles all of this

We kept hitting these same issues — wrong encoding assumptions, raw body bugs, framework quirks. So we built Tern to absorb all of it.

Signature verification — handled correctly

Base64 encoding, raw body extraction, correct header — all handled internally. You get a specific errorCode when something fails instead of a silent 400.

import { createWebhookHandler } from '@hookflo/tern/nextjs'

export const POST = createWebhookHandler({
  platform: 'shopify',
  secret: process.env.SHOPIFY_API_SECRET!,
  handler: async (payload) => {
    // verified — base64, raw body, all handled
  }
})

Same on Express, Cloudflare Workers and Hono. No raw body setup, no encoding decisions.

After verification — events still fail silently

Shopify retries failed webhooks but you have no visibility into what failed, why, or when. Merchants find out before you do.

Tern's optional reliability layer closes that gap — queue, retries, deduplication, dead letter queue and replay:

export const POST = createWebhookHandler({
  platform: 'shopify',
  secret: process.env.SHOPIFY_API_SECRET!,
  queue: {
    token: process.env.QSTASH_TOKEN!,
    retries: 3,
  },
  alerts: {
    slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
  },
  handler: async (payload) => {
    // queued, retried, alerted on failure
  }
})

Know when something fails before your merchants do.

verify → queue → retry → dedup → DLQ → replay → alert. the full inbound webhook loop, closed.

⭐ if this helped, a star means a lot — Tern
Docs: tern.hookflo.com
github.com/Hookflo/tern — open source, MIT licensed, zero lock-in.

Why Shopify Webhook HMAC Verification Keeps Failing

Prateek Jain — Fri, 06 Mar 2026 15:58:25 +0000

You set up the webhook. Got the secret. Wrote the HMAC check. Still getting:

HMAC VALIDATION FAILED

Or worse — it passes locally but fails Shopify's automated review. Here's every real reason it happens.

if you just want all of this handled without thinking about it — Tern fixes every issue below out of the box. keep reading to understand why.

1. You're using the wrong secret

This is the most common one and it's not obvious from the docs.

# ❌ wrong — this is the API key
SHOPIFY_API_KEY=abc123...

# ✅ correct — this is what signs webhooks
SHOPIFY_API_SECRET=shpss_xyz789...

If you're passing the wrong value here every HMAC will fail silently.

2. The signature is base64 — not hex

Shopify's X-Shopify-Hmac-SHA256 header is base64 encoded, not hex like Stripe.

Most HMAC examples online use .digest('hex'). That gives you the wrong output for Shopify.

// ❌ wrong encoding — hex output won't match
const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex')

// ✅ correct — base64 to match Shopify's header
const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('base64')

One word difference. Hours of debugging.

3. Raw body getting parsed before verification

Same problem as Stripe but Shopify's error message gives you even less to go on.

Your framework parses the body into a JavaScript object before your handler runs. You re-stringify it. The whitespace changes. The signature doesn't match.

// ❌ body is already a parsed object here
app.use(express.json())

app.post('/webhook', (req, res) => {
  const body = JSON.stringify(req.body) // not the original bytes
  // verification fails
})

Fix — raw body parser specifically for the webhook route:

// ✅raw bytes preserved
app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const hmac = req.headers['x-shopify-hmac-sha256']
    const signature = crypto
      .createHmac('sha256', process.env.SHOPIFY_API_SECRET)
      .update(req.body) // Buffer, not parsed object
      .digest('base64')

    if (signature !== hmac) return res.status(401).send('Unauthorized')
    res.status(200).send('OK')
  }
)

4. Shopify's automated review check failing

You test manually, everything works. You submit for app review, the HMAC check fails.

Make sure your handler responds correctly to:

customers/data_request
customers/redact
shop/redact

These are mandatory. If they return anything other than 200, the HMAC check is marked as failed even if your signature logic is correct.

5. Body consumed before your route runs

In Remix and some other frameworks, the authentication middleware reads the request body first. By the time your webhook handler runs, the stream is already consumed.

Fix — clone the request before anything touches it:

const reqClone = request.clone()
const rawPayload = await reqClone.text()
// use rawPayload for HMAC verification

The pattern underneath all of this

How Tern handles all of this

We kept hitting these same issues — wrong encoding assumptions, raw body bugs, framework quirks. So we built Tern to absorb all of it.

Signature verification — handled correctly

Base64 encoding, raw body extraction, correct header — all handled internally. You get a specific errorCode when something fails instead of a silent 400.

import { createWebhookHandler } from '@hookflo/tern/nextjs'

export const POST = createWebhookHandler({
  platform: 'shopify',
  secret: process.env.SHOPIFY_API_SECRET!,
  handler: async (payload) => {
    // verified — base64, raw body, all handled
  }
})

Same on Express, Cloudflare Workers and Hono. No raw body setup, no encoding decisions.

After verification — events still fail silently

Shopify retries failed webhooks but you have no visibility into what failed, why, or when. Merchants find out before you do.

Tern's optional reliability layer closes that gap — queue, retries, deduplication, dead letter queue and replay:

export const POST = createWebhookHandler({
  platform: 'shopify',
  secret: process.env.SHOPIFY_API_SECRET!,
  queue: {
    token: process.env.QSTASH_TOKEN!,
    retries: 3,
  },
  alerts: {
    slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
  },
  handler: async (payload) => {
    // queued, retried, alerted on failure
  }
})

Know when something fails before your merchants do.

verify → queue → retry → dedup → DLQ → replay → alert. the full inbound webhook loop, closed.

⭐ if this helped, a star means a lot — Tern
Docs: tern.hookflo.com
github.com/Hookflo/tern — open source, MIT licensed, zero lock-in.

Why Stripe Webhook Signature Verification Keeps Failing

Prateek Jain — Thu, 05 Mar 2026 18:39:02 +0000

You followed the docs. Copied the example. Added the signature check. Still getting:

No signatures found matching the expected signature for payload

Here's every real reason it happens and how to fix each one.

if you just want all of this handled without thinking about it Tern fixes every issue below out of the box. keep reading to understand why.

1. Your body is already parsed

This gets almost everyone the first time.

Stripe needs the raw bytes of the request body — exactly what it sent, untouched. If anything touches the body before your handler runs, the signature won't match.

In Express the problem is usually this:

// ❌ express.json() runs first — raw bytes are gone
app.use(express.json())

app.post('/webhook', (req, res) => {
  stripe.webhooks.constructEvent(req.body, sig, secret) // fails
})

Fix — give the webhook route its own raw body parser, separate from everything else:

// ✅ raw body only for this route
app.post('/webhook',
  express.raw({ type: '*/*' }),
  (req, res) => {
    stripe.webhooks.constructEvent(req.body, sig, secret) // works
  }
)

app.use(express.json()) // other routes unaffected

Middleware order matters. Webhook route gets raw body — everything else gets parsed JSON.

2. Test secret vs Live secret

Stripe gives you a different signing secret for test mode and live mode.

The Stripe CLI gives you one secret when you run stripe listen. Your Dashboard endpoint has a completely different one. Mixing them always fails silently.

# CLI secret only works with stripe listen
whsec_abc123...

# Dashboard secret — only works with real Stripe events  
whsec_xyz789...

Keep them separate and explicit:

STRIPE_WEBHOOK_SECRET_TEST=whsec_cli_secret
STRIPE_WEBHOOK_SECRET_LIVE=whsec_dashboard_secret

3. Timestamp tolerance — the debugging trap

Stripe embeds a timestamp in the signature. By default anything older than 5 minutes gets rejected. Replay attack protection.

When you replay an old event from the Dashboard, the timestamp is from when Stripe originally sent it — not now. If that was more than 5 minutes ago, verification fails even with the correct secret and correct body.

Temporarily extend tolerance while debugging:

// debugging only — never in production
stripe.webhooks.constructEvent(payload, sig, secret, 99999)

Better — use stripe trigger locally instead of replaying old events. Fresh timestamps every time.

stripe listen --forward-to localhost:3000/webhook
stripe trigger payment_intent.succeeded

4. A proxy is sitting in front of your server

Cloudflare, nginx, or any reverse proxy can modify request bytes before they reach your handler. Compression, encoding rules, security filters — any of these can break signature verification.

Symptom works locally, fails in production with the correct secret.

Quick check — bypass the proxy and hit your server directly. If verification passes, the proxy is the culprit. For Cloudflare, whitelist Stripe's IP ranges to pass through without transformation.

The pattern underneath all of this

Every one of these failures has the same root cause — something between Stripe and your verification code modified or lost the original request.

The verification logic itself is not complicated. The problem is always the plumbing around it.

How Tern fixes all of this

We kept hitting every one of these issues while building our own product Hookflo — raw body bugs, wrong secrets, localhost pain, silent failures in production. So we pulled the whole thing out into Tern, an open source SDK that absorbs all of it.

Signature verification — just works

Raw body extraction, timestamp validation, correct header parsing — handled internally for every framework. No middleware ordering to think about. If verification fails you get a specific errorCode like INVALID_SIGNATURE, TIMESTAMP_TOO_OLD, or MISSING_HEADER instead of the generic Stripe error.

import { createWebhookHandler } from '@hookflo/tern/nextjs'

export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  handler: async (payload) => {
    // verified — raw body handled, timestamp checked
  }
})

Works the same on Nextjs, Express, Cloudflare Workers and Hono. Same code, native adapter for each runtime.

No localhost tunneling headaches

Tern works with Stripe CLI out of the box. No ngrok, no extra setup:

stripe listen --forward-to localhost:3000/webhook
stripe trigger payment_intent.succeeded

After verification — the full loop

Once the signature passes, what happens next? Events fail silently. Customers email saying they missed 200 order updates. No visibility, no retries.

Tern has an optional reliability layer for exactly this — queue, retries, deduplication, dead letter queue and replay. Opt-in, bring your own Upstash account:

export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  queue: {
    token: process.env.QSTASH_TOKEN!,
    retries: 3,
  },
  handler: async (payload) => {
    // queued, retried on failure, deduplicated
  }
})

Know before your users do

Slack and Discord alerts when events fail or land in the dead letter queue. Optional, one config line:

alerts: {
  slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
}

verify → queue → retry → dedup → DLQ → replay → alert. the whole inbound webhook loop, closed.

Docs
github.com/Hookflo/tern — open source, MIT licensed, zero lock-in.

How to Verify Webhooks in Next.js (Stripe, GitHub, Polar, and More)

Prateek Jain — Fri, 20 Feb 2026 17:57:13 +0000

If you've ever built a SaaS product, you've written this code:

const sig = req.headers['stripe-signature']
const raw = await getRawBody(req)
const ts  = sig.split(',')[0].split('=')[1]
const s   = sig.split(',')[1].split('=')[1]
const pl  = `${ts}.${raw}`
const exp = createHmac('sha256', secret).update(pl).digest('hex')
if (!timingSafeEqual(Buffer.from(s), Buffer.from(exp))) throw new Error('401')
if (Date.now()/1e3 - Number(ts) > 300) throw new Error('replay attack')

Then three months later you add Polar. Then GitHub. Then Razorpay. Suddenly you have 200 lines of platform-specific signature verification code scattered across your codebase — all doing the same thing differently.

This post shows you how to do it once, cleanly, with @hookflo/tern.

Why Webhook Verification Is Harder Than It Looks

Every platform signs webhooks differently:

Stripe — t={timestamp},v1={signature} comma-separated, HMAC-SHA256, payload is timestamp.body
GitHub — sha256={signature} prefixed, HMAC-SHA256, payload is raw body
Polar — v1={signature} space-separated, Standard Webhooks spec, base64 encoded secret
WorkOS — millisecond timestamps (not seconds) — breaks every standard timestamp validator
fal.ai — ED25519 asymmetric crypto with JWKS key rotation, no shared secret at all

Each has subtle differences that are easy to get wrong. And wrong usually means silent failures — webhooks returning 400, retries flooding your server, events you never process.

Installation

npm install @hookflo/tern

Basic Usage — Next.js App Router

// app/api/webhooks/stripe/route.ts
import { createWebhookHandler } from '@hookflo/tern/nextjs'

export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  handler: async (payload) => {
    console.log(payload.type) // 'payment_intent.succeeded'
    return { received: true }
  }
})

That's it. Tern handles:

✅ Raw body extraction (the thing that breaks most webhook implementations)
✅ Signature verification with timing-safe comparison
✅ Replay attack protection via timestamp validation
✅ Proper error codes (MISSING_SIGNATURE, INVALID_SIGNATURE, TIMESTAMP_EXPIRED)

The Key Insight — Change One Word to Switch Platforms

// Stripe
export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  handler: async (payload) => ({ received: true })
})

// Polar — change one word
export const POST = createWebhookHandler({
  platform: 'polar',
  secret: process.env.POLAR_WEBHOOK_SECRET!,
  handler: async (payload) => ({ received: true })
})

// GitHub — change one word
export const POST = createWebhookHandler({
  platform: 'github',
  secret: process.env.GITHUB_WEBHOOK_SECRET!,
  handler: async (payload) => ({ received: true })
})

// Razorpay — change one word
export const POST = createWebhookHandler({
  platform: 'razorpay',
  secret: process.env.RAZORPAY_WEBHOOK_SECRET!,
  handler: async (payload) => ({ received: true })
})

Same API. Every platform. The underlying algorithm differences — base64 vs hex, milliseconds vs seconds, prefixed vs comma-separated — are all handled internally.

Error Handling

export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  onError: (error) => {
    console.error('Webhook failed:', error.errorCode)
    // MISSING_SIGNATURE | INVALID_SIGNATURE | TIMESTAMP_EXPIRED
  },
  handler: async (payload) => {
    return { received: true }
  }
})

Replay Attack Protection

Every platform that sends a timestamp gets automatic replay protection. If a webhook arrives more than 5 minutes after it was signed, Tern rejects it with TIMESTAMP_EXPIRED.

export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  toleranceInSeconds: 300, // default 5 minutes, adjust as needed
  handler: async (payload) => ({ received: true })
})

Custom Platforms

Not on the list? Pass your own config — works with any HMAC scheme:

export const POST = createWebhookHandler({
  platform: 'custom',
  secret: process.env.MY_WEBHOOK_SECRET!,
  signatureConfig: {
    algorithm: 'hmac-sha256',
    headerName: 'x-my-signature',
    headerFormat: 'raw',
    payloadFormat: 'raw',
  },
  handler: async (payload) => ({ received: true })
})

Supported Platforms

Platform	Algorithm	Status
Stripe	HMAC-SHA256	✅ Verified
GitHub	HMAC-SHA256	✅ Verified
Clerk	HMAC-SHA256	✅ Verified
Polar	HMAC-SHA256	✅ Verified
Shopify	HMAC-SHA256	✅ Verified
WorkOS	HMAC-SHA256	✅ Verified
Razorpay	HMAC-SHA256	✅ Verified
Replicate	HMAC-SHA256	✅ Verified
Paddle	HMAC-SHA256	✅ Verified
LemonSqueezy	HMAC-SHA256	✅ Verified
DodoPayments	HMAC-SHA256	✅ Verified
fal.ai	ED25519	✅ Verified

Why Not Just Use Each Platform's Official SDK?

You could. But:

Stripe's webhook verification ships as part of stripe — a 2MB package
GitHub's requires @octokit/webhooks as a separate dep
Polar, WorkOS, Razorpay, Replicate have no dedicated webhook verification packages

You end up with multiple packages, multiple APIs, multiple ways to extract the raw body. Tern is zero dependencies and one API for all of them.

The Raw Body Problem

One thing that breaks most webhook implementations in Next.js is raw body parsing. JSON middleware re-parses the body and you lose the original bytes needed for HMAC verification.

Tern handles this automatically — you never touch the raw body yourself.

// without tern — this breaks signature verification
export async function POST(req: Request) {
  const body = await req.json() // ← destroys raw body for HMAC
  // signature check will always fail from here
}

// with tern — just works
export const POST = createWebhookHandler({
  platform: 'stripe',
  secret: process.env.STRIPE_WEBHOOK_SECRET!,
  handler: async (payload) => ({ received: true })
  // raw body handled internally ✅
})

Getting Started

npm install @hookflo/tern

import { createWebhookHandler } from '@hookflo/tern/nextjs'

export const POST = createWebhookHandler({
  platform: 'stripe', // swap to any supported platform
  secret: process.env.WEBHOOK_SECRET!,
  handler: async (payload) => {
    // your logic here
    return { received: true }
  }
})

Links:

Built by Hookflo — webhook infrastructure for modern SaaS. Star the repo if this helped ⭐