What is On-Demand Revalidation?

What is On-Demand Revalidation?

On-demand revalidation is a cache invalidation strategy where statically generated pages are regenerated only when an explicit signal—typically an API call or webhook—tells the server that content has changed. Unlike time-based Incremental Static Regeneration (ISR), which rebuilds pages on a fixed interval (e.g., every 60 seconds), on-demand revalidation fires precisely when the underlying data updates. Next.js introduced this pattern in v12.1 (February 2022) via the res.revalidate() API, and it became the default mental model in the App Router with revalidatePath() and revalidateTag() starting in Next.js 13.4 (May 2023). The result is pages that stay static—serving at CDN speed—but never show stale content for longer than it takes the webhook to fire and the rebuild to complete. We use it on nearly every headless CMS project we ship, especially when editors expect publish-then-see-it-live in under two seconds.

How it works

The flow has three moving parts: a data source, a trigger mechanism, and the revalidation endpoint.

1. Data source changes. An editor publishes a blog post in a CMS like Sanity, Contentful, or Payload.
2. Webhook fires. The CMS sends an HTTP POST to a route in your app (e.g., /api/revalidate) with a payload describing what changed.
3. Server regenerates. Your route handler calls the framework's revalidation API, which purges the cached page and rebuilds it on the next request—or immediately, depending on configuration.

In the Next.js App Router (v13.4+), the code looks like this:

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const secret = req.headers.get('x-revalidation-secret');
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  const { tag } = await req.json();
  revalidateTag(tag);
  return NextResponse.json({ revalidated: true, tag });
}

On the data-fetching side, you tag your fetch calls:

const res = await fetch('https://cms.example.com/api/posts', {
  next: { tags: ['posts'] },
});

When the webhook hits /api/revalidate with { "tag": "posts" }, every page that used the posts tag gets purged and rebuilt. Vercel, Netlify, and Cloudflare all support this pattern at the CDN edge, so the stale page is replaced globally, not just on a single server.

When to use it

On-demand revalidation is the right choice when content changes are event-driven and infrequent-to-moderate (think blog posts, product pages, marketing landing pages). It gives you static performance with dynamic freshness.

Use it when:

• You have a headless CMS with webhook support (Sanity, Contentful, Strapi, Payload, etc.)
• Content updates happen on a human schedule (minutes to hours apart, not seconds)
• Stale content is a business problem—pricing pages, legal disclaimers, inventory counts
• You want CDN-level TTFB (often sub-50ms) without serving outdated data

Don't use it when:

• Data changes every few seconds (stock tickers, live scores)—use server rendering or streaming instead
• You have thousands of interdependent pages that all invalidate at once—this can cause a thundering herd of rebuilds
• Your hosting provider doesn't support on-demand purging at the edge (self-hosted Node without a CDN layer)

On-Demand Revalidation vs alternatives

Time-based ISR is simpler but wasteful—it rebuilds pages even when nothing changed and can still serve stale content within the window. SSR is always fresh but slower. On-demand revalidation sits in the sweet spot: you get static speed and only pay the rebuild cost when data actually changes. We've shipped this on 50+ projects and it's our default recommendation for any site backed by a CMS.

Real-world example

We built a 1,200-page e-commerce catalog on Next.js 14 with Sanity as the CMS, deployed to Vercel. Product pages were statically generated at build time with revalidateTag. When a merchandiser updated a price or toggled a product's availability in Sanity, a GROQ-powered webhook fired to our /api/revalidate route with the product's slug as the tag. The affected page was purged and rebuilt within 1.3 seconds on average. The site maintained a median TTFB of 38ms across all product pages (measured via CrUX), and editors stopped asking "why doesn't my change show up?"—a question that had plagued the old 60-second ISR setup.