Test Resend Webhooks Locally

From a stuck handler to a live Resend 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. 3Open the Webhooks page in Resend (resend.com/webhooks) and click Add Webhook. Paste your LocalCan URL with your route, e.g. https://your-app-12.localcan.dev/api/webhooks/resend, and select the events you want to observe. Then take that endpoint’s signing secret (the whsec_… value the create-webhook API returns as signing_secret) and store it as RESEND_WEBHOOK_SECRET. It is scoped to this one endpoint.
4. 4Fire a real event rather than a synthetic payload: mail bounced@resend.dev for email.bounced, complained@resend.dev for email.complained, delivered@resend.dev for email.delivered. All take a +label extension except the suppressed address. To re-send one you already have, go back to resend.com/webhooks, pick the endpoint, pick the message and click Replay.
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 (with svix-id and svix-timestamp)

Algorithm

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

What's signed

Resend delivers through Svix, so the signed string is {svix-id}.{svix-timestamp}.{raw body}: the svix-id header, a dot, the svix-timestamp header, a dot, then the exact bytes of the body. The HMAC key is not the whsec_ string: strip the prefix and base64-decode the remainder. The digest is base64-encoded and matched against each space-separated v1,<sig> entry in svix-signature. A timestamp more than five minutes from your clock in either direction is rejected before the digest is compared at all.

Secret

The signing_secret (whsec_…) issued when the endpoint was created, returned by the create-webhook API and shown on the endpoint at resend.com/webhooks. Resend’s examples store it as RESEND_WEBHOOK_SECRET. It is scoped to that single endpoint, so recreating the endpoint invalidates it.

// Next.js App Router. The SDK path: resend.webhooks.verify() wraps the
// standardwebhooks library, which strips the whsec_ prefix, base64-decodes the
// key, hashes "{id}.{timestamp}.{body}" and enforces the 5-minute tolerance.
import { NextResponse } from 'next/server'
import { Resend } from 'resend'

const resend = new Resend(process.env.RESEND_API_KEY)

export async function POST(req) {
  // RAW body. Never req.json() before verifying: parsing and re-serialising
  // changes the bytes and the digest can no longer match.
  const payload = await req.text()

  let event
  try {
    // The SDK renames these to webhook-id / webhook-timestamp / webhook-signature
    // internally; you still read the svix-* headers Resend puts on the wire.
    event = resend.webhooks.verify({
      payload,
      headers: {
        id: req.headers.get('svix-id'),
        timestamp: req.headers.get('svix-timestamp'),
        signature: req.headers.get('svix-signature'),
      },
      webhookSecret: process.env.RESEND_WEBHOOK_SECRET, // whsec_...
    })
  } catch (err) {
    // "No matching signature found"  -> wrong secret, or a parsed body
    // "Message timestamp too old"    -> outside the 5-minute window
    return new NextResponse('Invalid webhook: ' + err.message, { status: 400 })
  }

  // At-least-once delivery: dedupe on this id before you write anything.
  const messageId = req.headers.get('svix-id')

  if (event.type === 'email.bounced') {
    // suppress the address and flag the record, keyed on messageId
  }

  return NextResponse.json({ received: true })
}

A replayed capture verifies for five minutes and then stops. The svix-timestamp is part of what was signed, so it travels with the replay, and the library rejects anything outside the window with Message timestamp too old before it looks at the digest. The correct secret will not save you. Replay is the right tool while you iterate on a handler and the wrong one for a delivery from yesterday. For an old event, open the endpoint at resend.com/webhooks, select the message and click Replay: Resend redelivers it freshly signed.