Webhooks

Send inserts, updates, deletes and Auth events to your own HTTPS endpoint: signed, retried for 24 hours, logged with the response, and replayable.

A webhook sends an HTTPS POST to your endpoint each time a row in a chosen table is inserted, updated or deleted, or a user signs up, confirms, signs in, changes or is deleted. You don't write triggers or functions, and a slow or failing endpoint never slows down your database: events are queued and delivered in the background.

Create one in Studio under Database → Webhooks: a name, the endpoint URL, the events and, for database events, the tables. The signing secret is shown once you save; you can show it again later.

#Events

The user in Auth events has id, email, phone, the confirmation and sign-in times, user_metadata, app_metadata, is_anonymous and banned_until. Password hashes and tokens are never sent. TRUNCATE sends no events, and neither do changes made while triggers are off (for example a restore).

#Payload

{
  "id": "abcdefghijklmnop_4182",
  "type": "db.update",
  "created_at": "2026-10-25T12:00:00.000Z",
  "project_ref": "abcdefghijklmnop",
  "schema": "public",
  "table": "orders",
  "record": { "id": 42, "status": "paid", "total": 1999 },
  "old_record": { "id": 42, "status": "pending", "total": 1999 }
}

created_at is the time of the change, not of the delivery. If a row is larger than 256 KB, record and old_record keep only id and the payload has "truncated": true: read the row from the API instead.

#Verify the signature

Every request has these headers:

• StitchDB-Webhook-Id: the event id, the same on every retry. Use it to skip events you already processed.
• StitchDB-Webhook-Timestamp: Unix seconds when this attempt was sent.
• StitchDB-Event: the event type.
• StitchDB-Signature: v1=<hex>, the HMAC-SHA256 of <timestamp>.<raw body> with your signing secret.

import crypto from 'node:crypto'

// rawBody: the request body exactly as received (a string or Buffer), before JSON parsing.
export function verify(secret, headers, rawBody) {
  const ts = headers['stitchdb-webhook-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // older than 5 minutes
  const want = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex')
  const got = String(headers['stitchdb-signature'] || '')
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
}

const enc = new TextEncoder()

Deno.serve(async (req) => {
  const body = await req.text()
  const ts = req.headers.get('stitchdb-webhook-timestamp') ?? ''
  const key = await crypto.subtle.importKey('raw', enc.encode(Deno.env.get('WEBHOOK_SECRET')!), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, enc.encode(ts + '.' + body)))
  const want = 'v1=' + [...mac].map((b) => b.toString(16).padStart(2, '0')).join('')
  if (req.headers.get('stitchdb-signature') !== want || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return new Response('Bad signature', { status: 401 })
  }
  const event = JSON.parse(body)
  // … handle event.type
  return new Response('ok')
})

import hmac, hashlib, time

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers.get('StitchDB-Webhook-Timestamp', '')
    if abs(time.time() - int(ts or 0)) > 300:
        return False
    want = 'v1=' + hmac.new(secret.encode(), ts.encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(headers.get('StitchDB-Signature', ''), want)

#Delivery and retries

• Any 2xx answer within 15 seconds counts as delivered. Answer quickly and do slow work afterwards.
• Otherwise the event is retried after 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. After the last attempt it is marked Failed and kept in the log.
• Delivery is at least once: an event can arrive twice (for example after a timeout your endpoint did process). Order is not guaranteed between events; use created_at or your own version column when order matters.
• URLs must be https:// on a public address. Redirects are not followed. You can add up to 10 headers of your own (for example Authorization); they are stored encrypted.

#Delivery log and replay

Open a webhook in Studio to see every delivery: the request body, the status code and the first 2 KB of your endpoint's response, how long it took, and each attempt. Replay sends one delivery again; Replay failed sends every failed delivery again, oldest first. Send test sends a test.ping event right away and shows the answer, without logging or retrying it.

#When an endpoint keeps failing

If every delivery to a webhook has failed for an hour, the project owner gets an e-mail. After 3 days of failures the webhook is turned off and the owner gets another e-mail; the events it missed stay in the log, so fix the endpoint, turn the webhook on and use Replay failed.

#Limits

An event counts once however many webhooks receive it. When a project reaches its monthly limit, new events are not sent until the next month and the owner gets an e-mail; deliveries already queued are still sent.

#Management API

curl -X POST https://stitchdb.com/platform/v1/projects/<ref>/webhooks \
  -H "Authorization: Bearer $STITCHDB_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "name": "Orders", "url": "https://api.example.com/hooks", "events": ["db.insert", "db.update"], "tables": ["public.orders"] }'

Changing webhooks needs the Administrator role on the project (tokens: projects:write). To call other services from SQL yourself, see HTTP from SQL.