sanity-webhooks

Sanity Webhooks

When to Use This Skill

• How do I receive Sanity webhooks?
• How do I verify Sanity webhook signatures?
• Why is my sanity-webhook-signature verification failing?
• How do I trigger cache revalidation or search reindexing when a document changes?
• How do I handle document create, update, and delete events from the Content Lake?

How Sanity Webhooks Work

Sanity uses GROQ-powered webhooks. There are no fixed event-type strings. Instead, each webhook is configured at sanity.io/manage with:

• A GROQ filter that decides which document changes fire the webhook (e.g. _type == "post", or delta helpers like delta::changedAny(...)).
• A GROQ projection that shapes the request body (JSON). If left empty, the payload is the whole document after the change, which always includes _id, _type, and _rev.

Handlers therefore dispatch on the document's _type (and any fields you project), not on a provider-defined event name. Webhooks fire on create / update / delete in the Content Lake and ignore draft and version documents by default.

Verification (core)

Sanity signs with the official @sanity/webhook package (v4 requires Node 18+). The sanity-webhook-signature header is Stripe-style — t=<ms-timestamp>,v1=<sig> — an HMAC-SHA256 over `${timestamp}.${rawBody}` (timestamp in milliseconds), base64url encoded with no padding. Pass the raw request body — do not JSON.parse first.

const { isValidSignature, SIGNATURE_HEADER_NAME } = require('@sanity/webhook');
// SIGNATURE_HEADER_NAME === 'sanity-webhook-signature'

const signature = req.headers[SIGNATURE_HEADER_NAME];

// isValidSignature is async in v4+ and returns a boolean (never throws on a
// bad signature). It recomputes the HMAC from the timestamp in the header.
const valid = await isValidSignature(
  rawBody,                              // raw HTTP body string — NOT parsed JSON
  signature,
  process.env.SANITY_WEBHOOK_SECRET,   // secret from sanity.io/manage
);
if (!valid) return res.status(400).send('Invalid signature');