How to Use CMS Webhooks to Trigger Incremental Builds

CMS webhooks are HTTP callbacks that fire automatically when content changes in your headless CMS. Instead of polling for updates or rebuilding your entire site on a fixed schedule, webhooks let your build system react instantly and surgically — rebuilding only the pages that were actually affected by the change.

How Sanity Webhooks Work

When a document is created, updated, or deleted in Sanity Studio, Sanity's backend evaluates any configured webhooks. If the document matches the webhook's GROQ filter, Sanity sends an HTTP POST request to your specified endpoint. The payload contains the document ID, document type, and the operation that triggered the event.

Webhooks are configured in the Sanity management console at sanity.io/manage. Navigate to your project, select the API tab, and open the Webhooks section. Each webhook requires:

• A name to identify the webhook
• A URL — the endpoint that will receive the POST request
• A dataset (e.g. production)
• A GROQ filter to scope which documents trigger the webhook
• A secret for verifying the request signature

Configuring a Webhook with a GROQ Filter

GROQ filters are the most powerful feature of Sanity webhooks. They let you fire the webhook only when a document of a specific type changes, or even when a specific field on that document changes. This prevents unnecessary build triggers from unrelated content updates.

For example, to fire only when a published blog post changes, use this filter:

_type == "post" && !(_id in path("drafts.**"))

The !(_id in path("drafts.**")) clause ensures the webhook only fires when a document is published, not when a draft is saved. This is critical — without it, every autosave in the Studio would trigger a build.

You can also scope to multiple document types:

(_type == "post" || _type == "author" || _type == "category") && !(_id in path("drafts.**"))

The Webhook Payload

When Sanity fires a webhook, the POST body contains a JSON payload. The default payload includes the document ID, type, and the triggering operation. Here is a representative example:

{
  "_id": "abc123",
  "_type": "post",
  "_rev": "xyz789",
  "operation": "update",
  "projectId": "your-project-id",
  "dataset": "production"
}

You can also configure a custom projection in the webhook settings to include additional fields from the document in the payload, which is useful when your revalidation logic needs to know the document's slug or other routing information.

Verifying the Webhook Signature

Every Sanity webhook can be configured with a secret. Sanity signs the request body using HMAC-SHA256 and includes the signature in the sanity-webhook-signature header. You must verify this signature in your endpoint before processing the payload — otherwise, anyone who discovers your endpoint URL could trigger spurious rebuilds.

import { isValidSignature, SIGNATURE_HEADER_NAME } from '@sanity/webhook'

export async function POST(req: Request) {
  const body = await req.text()
  const signature = req.headers.get(SIGNATURE_HEADER_NAME) ?? ''
  const secret = process.env.SANITY_WEBHOOK_SECRET!

  const isValid = await isValidSignature(body, signature, secret)

  if (!isValid) {
    return new Response('Invalid signature', { status: 401 })
  }

  const payload = JSON.parse(body)
  // proceed with revalidation...
}

On-Demand Revalidation in Next.js

Next.js App Router supports on-demand revalidation via revalidatePath() and revalidateTag(). This lets you invalidate the cache for specific pages or data tags without triggering a full site rebuild. Combined with Sanity webhooks, this is the most efficient way to keep a statically generated Next.js site up to date.

The general flow is:

1. An editor publishes a change in Sanity Studio.
2. Sanity evaluates the webhook filter and fires a POST to your Next.js API route.
3. Your API route verifies the signature, extracts the document ID and type, and calls revalidatePath() or revalidateTag().
4. Next.js purges the cached page and regenerates it on the next request.
5. The visitor sees fresh content — typically within seconds of the publish action.

Full Revalidation API Route

// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache'
import { isValidSignature, SIGNATURE_HEADER_NAME } from '@sanity/webhook'
import { NextRequest, NextResponse } from 'next/server'

const DOC_TYPE_TO_PATH: Record<string, string> = {
  post: '/blog',
  author: '/about',
  category: '/blog',
}

export async function POST(req: NextRequest) {
  const body = await req.text()
  const signature = req.headers.get(SIGNATURE_HEADER_NAME) ?? ''
  const secret = process.env.SANITY_WEBHOOK_SECRET!

  const isValid = await isValidSignature(body, signature, secret)
  if (!isValid) {
    return NextResponse.json({ message: 'Invalid signature' }, { status: 401 })
  }

  const { _type, _id, slug } = JSON.parse(body)

  // Revalidate by tag (preferred — granular)
  revalidateTag(`sanity:${_type}`)
  revalidateTag(`sanity:${_id}`)

  // Also revalidate the path if we know it
  const path = DOC_TYPE_TO_PATH[_type]
  if (path) revalidatePath(path)
  if (slug?.current) revalidatePath(`/blog/${slug.current}`)

  return NextResponse.json({ revalidated: true, type: _type, id: _id })
}

Tagging Fetch Requests for Granular Invalidation

For revalidateTag() to work, your data-fetching calls must be tagged at the time of the request. In Next.js App Router, you add tags to the fetch options:

// lib/sanity.fetch.ts
import { client } from './sanity.client'

export async function getPost(slug: string) {
  return client.fetch(
    `*[_type == "post" && slug.current == $slug][0]`,
    { slug },
    {
      next: {
        tags: [`sanity:post`, `sanity:post:${slug}`],
      },
    }
  )
}

export async function getAllPosts() {
  return client.fetch(
    `*[_type == "post"] | order(publishedAt desc)`,
    {},
    {
      next: {
        tags: ['sanity:post'],
      },
    }
  )
}

When the webhook fires and calls revalidateTag('sanity:post'), Next.js invalidates every cached response that was tagged with that value — including both the post listing page and any individual post pages that fetched data with that tag.

Deploying the Webhook Endpoint

Your revalidation endpoint must be publicly accessible. When deploying to Vercel, the URL will be something like https://your-site.vercel.app/api/revalidate. Register this URL in the Sanity webhook configuration along with your secret. Store the secret in your deployment environment as SANITY_WEBHOOK_SECRET — never hardcode it.

During local development, use a tunneling tool such as ngrok or Cloudflare Tunnel to expose your local server and test the webhook end-to-end before deploying.