Test Supabase Webhooks Locally

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

1. 1Start LocalCan and point it at your local server: localcan http 54321. 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. 3For a Database Webhook: Dashboard → Database → Webhooks → Create a new hook, point the URL at your LocalCan address with your path, e.g. https://your-app-12.localcan.dev/webhook, pick the table and INSERT/UPDATE/DELETE events. These are unsigned, so add an HTTP header yourself (e.g. x-webhook-secret) and bump the request timeout above the 2000ms default. For an Auth Hook: Authentication → Hooks, choose the hook (Send Email, Custom Access Token…), set the same …localcan.dev URL, and copy the generated v1,whsec_… secret.
4. 4Database Webhook: there is no Resend button — pg_net is fire-and-forget. Trigger the real row change in the SQL Editor, e.g. insert into your_table (col) values ('x');, then check delivery with select * from net._http_response order by created desc limit 5;. Auth Hook: run the underlying flow — sign up or request a magic link for Send Email, request an OTP for Send SMS, log in for Custom Access Token.
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

webhook-signature (Auth Hooks only; Database Webhooks are unsigned)

Algorithm

HMAC-SHA256, base64-encoded — header value is v1,<base64>

What's signed

There is no single answer because there are two systems. Database Webhooks sign nothing — the only authenticity check is whatever custom header (e.g. x-webhook-secret) you added when creating the hook. Auth Hooks follow the Standard Webhooks spec: the signed string is {webhook-id}.{webhook-timestamp}.{raw body} — the webhook-id, a literal dot, the webhook-timestamp, another dot, then the exact request bytes — HMAC-SHA256 with the decoded secret, base64-encoded, and presented as v1,<base64> (space-delimited if multiple versions are present for key rotation).

Secret

Database Webhooks: no secret exists by default — you invent one and pass it as a header, then verify it yourself. Auth Hooks: generate it in Authentication → Hooks; the Dashboard/config.toml value is the full v1,whsec_<base64> string, but the standardwebhooks library expects the secret with the v1,whsec_ prefix STRIPPED. Note the config quirk: the env var name is singular (SEND_EMAIL_HOOK_SECRET), while the config.toml field is plural to allow comma-separated rotation: secrets="env(SEND_EMAIL_HOOK_SECRET)".

import express from 'express'
import { Webhook } from 'standardwebhooks'

// Auth Hook secret from the Dashboard looks like 'v1,whsec_<base64>'.
// The standardwebhooks library wants it WITHOUT the 'v1,whsec_' prefix.
const raw = process.env.SEND_EMAIL_HOOK_SECRET // 'v1,whsec_...'
const secret = raw.replace('v1,whsec_', '')
const wh = new Webhook(secret)

const app = express()

// Standard Webhooks signs the RAW body — mount express.raw, not express.json.
app.post('/auth-hook', express.raw({ type: 'application/json' }), (req, res) => {
  const headers = {
    'webhook-id': req.headers['webhook-id'],
    'webhook-timestamp': req.headers['webhook-timestamp'],
    'webhook-signature': req.headers['webhook-signature'],
  }
  try {
    // verify() rebuilds '{id}.{timestamp}.{body}', HMAC-SHA256, base64,
    // and checks the timestamp tolerance. Throws on mismatch or stale ts.
    const payload = wh.verify(req.body, headers)
    res.json({ ok: true })
  } catch (err) {
    res.status(401).send('Auth Hook verify failed: ' + err.message)
  }
})

// Database Webhooks are UNSIGNED — verify your own custom header instead.
app.post('/db-webhook', express.json(), (req, res) => {
  if (req.headers['x-webhook-secret'] !== process.env.DB_WEBHOOK_SECRET) {
    return res.status(401).send('bad secret')
  }
  const { type, table, record, old_record } = req.body
  // DELETE has record:null; INSERT has old_record:null — guard before reading.
  res.json({ received: type })
})