Next.js 16 Revalidation: What the Docs Actually Say

A Sanity webhook was firing, getting 200s, and revalidating something - yet the live page did not update. Editors saved, the Content Lake knew, the CDN knew, and the browser kept showing yesterday's content. This is the story of that bug.

The setup

Blog content lives in Sanity with a fetch client on useCdn: true. A route handler verifies the webhook signature and calls revalidatePath plus revalidateTag. The official guidance is in the Sanity best practices and the Next.js caching docs, not the toolkits' READMEs.

Where it broke

Three things lined up to keep the stale page alive:

1. The CDN can lag a few seconds after a mutation, so regenerating the instant a webhook lands can read pre-mutation data and stamp that as fresh.
2. revalidateTag with the second-argument profile set to max marks data stale and stale-serves it with SWR for up to a year. Great for set-and-forget, wrong for editorial content.
3. The Next.js data cache survives redeployments on some hosts, so an old entry keeps being served until something forces the next request to be a cache miss.

The fix

Use the webhook helper with its default wait for Content Lake eventual consistency, and invalidate with a blocking expire so the next request regenerates instead of re-serving stale. The explains it better than I can:

See the webhook best practices in the Sanity docs