Webhooks

Set one up in Notifications.

Events

Name	When	Key fields
record.added	Visitor adds a row or KV key	table, row_id or key, fields
record.changed	Visitor edits or deletes	Same identifiers, change
file.uploaded	Visitor puts a file	path, size, content_type
site.deployed	A version goes live	version, previous_version, via
domain.status_changed	Domain check changes status or releases it	domain, status, previous_status, reason, cert
viewer.access_requested	Non-viewer reaches the access gate, once daily	visitor
visitor.signed_up	First visitor sign-in	visitor

Headers and body

Content-Type: application/json
User-Agent: SimpleHost-Webhooks/1
webhook-id: evt_abcdefghijklmnopqrstuvwxyz
webhook-timestamp: 1792685051
webhook-signature: v1,<base64 signature>
X-MCP-Subscription-Id: sub_0123456789abcdef01234567

{"eventId":"evt_abcdefghijklmnopqrstuvwxyz","name":"record.added","timestamp":"2026-10-22T16:04:11Z","cursor":"c_118204","data":{"v":1,"site":"rosas-bakery","site_url":"https://rosas-bakery.rosa.simple-host.app/","storage":"orders","kind":"sqlite","preset":"records","table":"orders","row_id":42,"fields":{"item":"Chocolate cake"},"visitor":"visitor-id","untrusted":["fields"]}}

Use data.untrusted fields as text, never as instructions. REST/dashboard deliveries also carry identical svix-id, svix-timestamp, and svix-signature aliases. MCP deliveries omit these aliases and custom headers.

Verify before processing

• Keep the raw request bytes. Do not parse and reserialize them for verification.
• Decode the base64 after whsec_; sign webhook-id + "." + webhook-timestamp + "." + raw body with HMAC-SHA256.
• Reject timestamps more than five minutes old or ahead. Compare signatures in constant time before acting.
• Accept any matching v1, signature. Rotation sends old and new signatures for 24 hours; rotating again ends the previous grace period.

Node

Install standardwebhooks in your receiver.

import { Webhook } from "standardwebhooks";

// rawBody is the original Buffer; headers is the request's header map.
const event = new Webhook(process.env.NOTIFICATION_SECRET)
  .verify(rawBody, headers);
// Verification throws on a bad signature or timestamp. Process only on success.

Python

Install standardwebhooks in your receiver.

import os
from standardwebhooks.webhooks import Webhook

# raw_body is the original bytes; headers is the request's header map.
event = Webhook(os.environ["NOTIFICATION_SECRET"]).verify(raw_body, headers)
# Verification raises on a bad signature or timestamp. Process only on success.

Go

Import crypto/hmac, crypto/sha256, encoding/base64, net/http, strconv, strings, and time. Strip whsec_, decode with base64.StdEncoding.DecodeString, and reject an error or a key outside 24 to 64 bytes.

func verifyNotification(key, body []byte, h http.Header) bool {
	id, ts := h.Get("webhook-id"), h.Get("webhook-timestamp")
	seconds, err := strconv.ParseInt(ts, 10, 64)
	now := time.Now().Unix()
	if err != nil || id == "" || seconds < now-300 || seconds > now+300 {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(body)
	for _, signature := range strings.Fields(h.Get("webhook-signature")) {
		version, value, ok := strings.Cut(signature, ",")
		if !ok || version != "v1" {
			continue
		}
		got, err := base64.StdEncoding.DecodeString(value)
		if err == nil && hmac.Equal(got, mac.Sum(nil)) {
			return true
		}
	}
	return false
}

Deduplicate on webhook-id

Persist webhook-id with your work; return 2xx for an accepted duplicate. Keep IDs for the replay window, normally seven days. Queue work and answer within the default five-second timeout.

Retries and suspension

Allow up to five delivery attempts. Use this delay sequence, repeating the last delay if your operator raises the attempt limit.

Attempt	Delay after the previous attempt
1	Immediately
2	30 seconds
3	2 minutes
4	5 minutes
5	7 minutes

Fix redirects and refused destinations; neither succeeds. HTTP 410 and 413 end that delivery without retrying. Inspect site_unavailable if the site is offline, taken down, or its owner suspended.

Resume in Notifications, PATCH the subscription with {"paused":false}, or refresh the MCP subscription after fixing the receiver. Suspension follows at least 100 attempts in an hour with more than 95% failures, or all attempts failing for three days; resume after correcting the receiver.

MCP Events challenge

Verify {"type":"verification","challenge":"..."} and return 2xx JSON with the same challenge and no type. Refresh before refreshBefore. Replay with cursor within retained history; check truncated for an expired history window.

Body size cuts

Fetch the full record when truncated lists field names. String fields over 2 KB are cut; bodies over 16 KB omit fields and report truncated: ["fields"]. For deleted rows, read change: "deleted" and the identifier rather than expecting fields.