Top 5 Webhook Patterns Every Headless CMS Team Should Master

Your search index is three hours stale, your CDN is serving a product page with last week's price, and nobody noticed until a customer did. The culprit is almost always the same: a webhook that fires on every keystroke, or one that never fires on the delete, or a handler that swallowed an exception and moved on. Webhooks are the nervous system of a headless stack, and most teams wire them once, badly, then spend a year debugging the noise.

This is where Sanity earns its place as the Content Operating System for the AI era, the intelligent backend that treats content changes as first-class, queryable events rather than fire-and-forget HTTP calls. In Sanity, both the trigger filter and the payload projection are written in GROQ, so you decide precisely which changes matter and exactly what shape arrives at your endpoint.

This is a ranked field guide to five webhook patterns every headless team should master, from delta-aware filtering to on-infrastructure Functions. Each pattern maps to a real failure mode, shows the mechanism that fixes it, and marks where a given platform helps or gets in the way.

1. Delta-aware triggers: fire only when the field you care about actually changes

The most common webhook failure is volume. A naive webhook subscribes to every update on a document type, so a downstream system that only cares about the published title gets pinged when an editor tweaks an unrelated internal note, reorders an array, or fixes a typo in a draft. Multiply that across a busy editorial team and your endpoint is doing thousands of no-op invocations a day, each one a retry risk and a line on your observability bill.

The fix is to make the trigger understand change, not just existence. Sanity webhooks express their trigger filter in GROQ, the same expression you would normally put between the brackets in a query, and that filter has access to the delta:: namespace with before() and after(). The Delta-GROQ functions, before(), after(), delta::changedAny(), and delta::changedOnly(), let a webhook fire only when specific fields genuinely differ between the previous and current revision. A filter such as before().title != after().title is the core mechanism for cutting noise: the handler runs when the title moves and stays quiet otherwise.

A concrete example: you re-render a static sitemap only when a slug or a title changes. Without delta functions you rebuild on every save. With delta::changedAny((slug, title)) in the filter, the rebuild fires on the two fields that affect the sitemap and ignores the rest. Note also that webhooks trigger on create, update, and delete, and ignore the drafts. and versions. namespaces by default; turning draft triggers on will flood the endpoint because almost every Studio keystroke is an update. Delta-aware filtering is the difference between a webhook you trust and one you mute in Slack.

2. Payload shaping with GROQ projections: send exactly what the receiver needs

The second pattern addresses the other half of the wasteful webhook: the payload. Most platforms hand your endpoint the whole document, or a fixed representation of it, which forces the receiver to re-fetch references, discard fields it does not use, and reason about a shape it did not choose. That coupling is where webhook consumers rot. A schema change upstream quietly breaks a parser downstream because the payload carried far more than the contract required.

Sanity solves this by writing the payload as a GROQ projection, the same projection syntax you use in a normal query, so the webhook body is shaped at the source. You ask for exactly the fields you need, resolve references with the -> operator in one pass, and rename or compute values inline. A projection like {_id, title, "slug": slug.current, "authorName": author->name, "category": category->title} means the receiver gets a flat, stable object rather than a raw document plus a pile of unresolved references. Projections can also read sanity::projectId() and sanity::dataset(), so a single handler serving multiple environments knows which one sent the event.

Consider a search re-indexing endpoint. Instead of receiving a document and issuing three follow-up API calls to hydrate its references, the projection resolves the author, category, and computed slug before the request ever leaves Content Lake. The handler becomes a thin function that maps a known payload to an index document. This is the Model your business pillar in practice: the shape of the event follows the shape of your content model, not a lowest-common-denominator envelope, and the contract between producer and consumer is explicit and versionable.

3. Signed, idempotent delivery: treat every webhook as an untrusted, retried request

Patterns one and two make webhooks quiet and precise. Pattern three makes them safe. Two failure modes dominate production incidents here. First, an unauthenticated endpoint that anyone who learns the URL can POST to, which turns your re-index or your cache-purge into an attack surface. Second, a handler that assumes exactly-once delivery, so a legitimate retry double-charges, double-sends, or double-writes. Any at-least-once delivery system, which is what webhooks fundamentally are, will retry, and your handler has to be built for it.

Sanity webhooks support secret-based signing with Stripe-style signature verification, so your endpoint validates that a request genuinely originated from your project before it does any work. Reject the request when the signature check fails; do not log the payload and continue. For retries, Sanity sends an idempotency-key header, so a handler can record processed keys and short-circuit duplicates safely. The request also carries sanity- prefixed headers, including sanity-transaction-id, sanity-document-id, sanity-operation, sanity-project-id, and sanity-dataset, which give you everything you need to key, route, and trace an event without parsing the body.

Error handling belongs in this pattern too, and the discipline is borrowed straight from tool design: the model, or in this case the downstream system, handles errors when you write the errors for it. Every catch block is a signal you want to log, and every structured error is something a recovery process can act on. A bare exception bubbles up as an opaque 500 and triggers a blind retry. A structured, typed error response lets your queue decide whether to retry, dead-letter, or alert. Combined with Sanity's one-concurrent-request limit and retry policy, a signed and idempotent handler is what keeps at-least-once delivery from becoming at-least-twice damage.

4. Downstream freshness: keep every search index, cache, and channel in sync from one source

The fourth pattern is the one that quietly consumes roadmaps. The moment content lives in more than one place, a search index, a CDN cache, a vector store for retrieval, a mobile app cache, those copies drift. A price changes, an article publishes, a record is deleted, and every downstream copy has to know. Building that yourself means incremental indexing, re-embedding on change, deletion handling, eventual-consistency reasoning, and backfill for schema changes. As the field guide puts it, when it is a separate vector DB plus glue code, freshness becomes a permanent line item on your roadmap.

Webhooks and Functions are how you wire content-change events into re-indexing and re-embedding so that freshness stops being a maintenance burden. When retrieval is wired into the content backend rather than bolted onto a separate store, the freshness problem stops being something you maintain. A delete event fires a webhook that removes the document from the index; a publish event fires one that re-embeds and upserts it. Because the payload is a GROQ projection, the re-index handler receives the exact fields the index expects, with references already resolved.

This is the Power anything pillar: a single change in Content Lake fans out to every channel that needs it, whether that is a Next.js ISR revalidation, an Algolia upsert, or a semantic index that later answers a hybrid query like score(boost([title] match text::query($q), 2), text::semanticSimilarity($q)). The keyword predicate and the semantic score both depend on the index being current, and current is exactly what an event-driven freshness pipeline guarantees. One source of truth, many synchronized destinations, no cron job pretending to be a sync layer.

5. On-infrastructure Functions: skip the receiver you would otherwise operate and scale

The final pattern questions the premise of the previous four. Every external webhook needs a receiver: a service you deploy, secure, monitor, autoscale, and page someone about at 3am. For a large class of content-reaction work, that infrastructure is pure overhead. Sanity Functions are the on-infrastructure alternative: small, single-purpose Node.js v24.x functions that run on Sanity's cloud and react to content changes without any server of your own.

Document functions use the sanity.function.document trigger and the defineDocumentFunction helper, and Blueprints describe when and where a function runs. Functions refine their triggers and payloads with the same GROQ filters and projections you use for webhooks, so everything from patterns one and two carries over: delta-aware firing and exact payload shaping, minus the receiver. Beyond document functions, there are Scheduled functions using sanity.function.cron, Sync tag invalidate functions, and Media Library Asset functions, which cover recurring jobs, cache invalidation, and asset processing respectively.

A concrete example: an editor publishes an article, a document function fires, generates a summary, writes it back to the document, and enqueues a re-index, all without a single line of deployment YAML for a service of your own. The honest boundary is that Functions run in Sanity's runtime, so when you need a handler inside your own VPC, next to a private database, an external signed webhook is still the right tool. That is precisely why mastering both matters: reach for Functions when the work is content-shaped and on-infrastructure, and reach for a signed webhook when the work belongs in your systems. This is the Automate everything pillar with the infrastructure removed from the equation.