Next.js with a Headless CMS

The plain-language idea

A headless CMS (Contentful, Sanity, Payload, Strapi, and similar tools) is a content editor's admin UI plus an API — no templating, no frontend of its own. Your Next.js app owns the actual pages; the CMS is just where non-developers write and publish content, and where your app fetches it from. The "headless" part is the whole pitch: an editor can hit publish without a developer touching code, and the app decides how that content actually renders.

The fetch itself is the easy part — it's a normal fetch call inside a Server Component, same as fetching from any other API. The genuinely hard part is staleness: your pages are cached (statically generated, or fetched with Next.js's fetch cache), so a publish in the CMS doesn't automatically appear on the live site. The fix is the on-demand-revalidation webhook pattern — the CMS calls a Route Handler in your app the instant something is published, and that handler tells Next.js's cache exactly what just went stale.

See it in a real thing: fetching content, and reacting to a publish event

// app/blog/[slug]/page.tsx
export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;

  const res = await fetch(`https://cms.example.com/api/posts/${slug}`, {
    next: { tags: [`post-${slug}`] }, // tag this fetch so a webhook can invalidate exactly this post
  });
  const post = await res.json();

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.bodyHtml }} />
    </article>
  );
}

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

export async function POST(request: Request) {
  const secret = request.headers.get("x-webhook-secret");
  if (secret !== process.env.CMS_WEBHOOK_SECRET) {
    return NextResponse.json({ message: "Invalid secret" }, { status: 401 });
  }

  const { slug } = await request.json();
  revalidateTag(`post-${slug}`, { expire: 0 }); // immediate: a webhook can't use updateTag, it isn't a Server Action

  return NextResponse.json({ revalidated: true, slug });
}

The CMS is configured (in its own admin UI, not in this app's code) to POST to /api/revalidate whenever a post is published — this is the "on-demand-revalidation webhook pattern" by name: a webhook is just an HTTP callback a third-party service makes into your app when something happens on their end. The secret header check matters because this endpoint is public by necessity (the CMS has to be able to reach it from outside your network) — without it, anyone who finds the URL could trigger cache invalidation, which isn't a data breach but is a real denial-of-service angle against your caching.

What people usually miss

Watch out

• The webhook has to be configured in the CMS's own admin panel, not in Next.js. Nothing in the app code makes the CMS call the endpoint — that wiring lives entirely on the CMS side, as a "publish webhook" or similar setting a non-developer could accidentally disable.
• An unauthenticated revalidation endpoint is a real vulnerability, not just sloppy. Anyone who discovers the URL can spam it, forcing constant cache misses and origin refetches — a webhook secret (or a signed payload, for CMSs that support it) is the minimum bar, not an optional hardening step.
• Preview/draft content and published content are different problems. An editor wanting to see an unpublished draft before it's public needs Next.js's Draft Mode, not a webhook — the webhook pattern here is specifically about published content reaching already-cached live pages faster.
• revalidateTag inside a webhook Route Handler needs the immediate-expiry form. updateTag — the tool for instant read-your-own-writes — only works inside Server Actions; a Route Handler receiving a third-party webhook has to use revalidateTag(tag, { expire: 0 }) instead.
• Tag granularity is a real design decision, not an afterthought. Tagging every fetch with one single "cms-content" tag means every publish anywhere invalidates and refetches the entire site's cached content; tagging per-entity (post-${slug}) means a single publish only invalidates what actually changed.

The genealogy: on-demand revalidation, applied to a real trigger

This lesson doesn't reintroduce revalidateTag, revalidatePath, or updateTag from scratch — the on-demand revalidation lesson already covers what each does and when to reach for which. What's new here is the trigger: a third-party webhook calling into a Route Handler, which is exactly the "revalidateTag with immediate expiry, because updateTag isn't available outside a Server Action" case that lesson calls out.