Test Clerk Webhooks Locally

From a stuck handler to a live Clerk 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. 3In the Clerk Dashboard go to Webhooks → Add Endpoint and paste your LocalCan URL with your route, e.g. https://your-app-12.localcan.dev/api/webhooks. Subscribe to the events you need (user.created, session.created, …), then open the endpoint and reveal its Signing Secret (whsec_…). Clerk recommends storing it as CLERK_WEBHOOK_SIGNING_SECRET.
4. 4On the endpoint, open the Testing tab, pick an event in the Select event dropdown (e.g. user.created) and click Send Example to fire a synthetic payload. For a real delivery that failed, expand it in the Message attempts table to read the response code, then use the row menu → Replay to resend that exact message.
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

svix-signature

Algorithm

HMAC-SHA256, base64-encoded (space-delimited v1,<sig> list)

What's signed

Clerk (via Svix) signs the string {svix-id}.{svix-timestamp}.{raw body}: the svix-id header, a literal dot, the svix-timestamp header, a literal dot, then the exact bytes of the request body. The HMAC-SHA256 key is NOT the whsec_ string itself: strip the whsec_ prefix and base64-decode the rest to get the key bytes. The result is base64-encoded and compared against each space-separated v1,<sig> entry in svix-signature (strip the v1, prefix; at least one must match).

Secret

The endpoint Signing Secret (whsec_…) from Clerk Dashboard → Webhooks → your endpoint → Signing Secret (click the eye icon). Clerk recommends CLERK_WEBHOOK_SIGNING_SECRET. Despite the prefix it is a Svix base64 secret: verifyWebhook() and the svix library base64-decode it for you; only hand-rolled HMAC has to do it manually.

// Clerk's own scheme, by hand, so the verification is explicit.
// In production prefer verifyWebhook() from @clerk/nextjs/webhooks (or the svix
// lib). It does the base64 secret decode, the v1, prefix strip and the
// 5-minute timestamp check for you.
import crypto from 'crypto'

function verifyClerkWebhook(rawBody, headers, signingSecret) {
  const svixId = headers['svix-id']
  const svixTimestamp = headers['svix-timestamp']
  const svixSignature = headers['svix-signature']
  if (!svixId || !svixTimestamp || !svixSignature) {
    throw new Error('missing one of svix-id / svix-timestamp / svix-signature')
  }

  // 5-minute replay window (Svix default): reject stale or future timestamps.
  const now = Math.floor(Date.now() / 1000)
  const sent = parseInt(svixTimestamp, 10)
  if (Math.abs(now - sent) > 60 * 5) {
    throw new Error('svix-timestamp outside the 5-minute tolerance')
  }

  // whsec_ secret is base64 AFTER the prefix: decode it to raw key bytes.
  const key = Buffer.from(signingSecret.replace(/^whsec_/, ''), 'base64')

  // Sign "{svix-id}.{svix-timestamp}.{raw body}", raw body, never re-stringified.
  const signedContent = svixId + '.' + svixTimestamp + '.' + rawBody
  const expected = crypto.createHmac('sha256', key).update(signedContent).digest('base64')

  // svix-signature is a space-delimited list of "v1,<base64sig>" (key rotation).
  // Strip the "v1," version prefix and match at least one in constant time.
  const ok = svixSignature.split(' ').some((entry) => {
    const sig = entry.split(',')[1]
    if (!sig || sig.length !== expected.length) return false
    return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  })
  if (!ok) throw new Error('no v1 signature matched the expected HMAC')
  return JSON.parse(rawBody)
}

// Next.js App Router: read the RAW body, never the parsed JSON.
export async function POST(req) {
  const rawBody = await req.text()
  const headers = Object.fromEntries(req.headers)
  try {
    const evt = verifyClerkWebhook(rawBody, headers, process.env.CLERK_WEBHOOK_SIGNING_SECRET)
    if (evt.type === 'user.created') {
      // mirror the user into your DB
    }
    return new Response('ok', { status: 200 })
  } catch (err) {
    return new Response('Webhook Error: ' + err.message, { status: 400 })
  }
}

A replayed capture verifies for five minutes and then stops. Svix signs svix-timestamp into the digest and enforces a five-minute tolerance, so Replay is the right tool while you iterate on a handler and the wrong one for something captured an hour ago. That fails as too old even with the correct secret. For an older event, use Replay in the Dashboard’s Message attempts table, which redelivers it freshly signed.