Cache tags by domain: invalidation taxonomy, webhook wiring, and the over-invalidation storm

revalidateTag mechanics: invalidation by meaning, not by URL

Before you write your first revalidateTag call, ask: does the tag name say what changed, or just that something did? The answer determines whether a footer typo costs you one page or the whole site.

A tag is attached when the cache entry is written — fetch(url, { next: { tags: ['catalog:product:42'] } }) — and revalidateTag('catalog:product:42') marks every entry carrying that tag stale, wherever it was used: product page, search result, home carousel. That is the power over revalidatePath: you invalidate by domain meaning, not by enumerating URLs that might embed the data. The semantics are worth stating precisely. revalidateTag does not regenerate anything eagerly — it marks entries stale, and the next request for an affected page re-fetches and rebuilds (with the stampede characteristics you met in the ISR lesson: many concurrent misses hit the origin together). Called inside a Server Action, it additionally refreshes the client’s router view on completion; called from a route handler — the webhook case — pages refresh on their next visit. One more boundary: tags ride on the Data Cache, so they apply to fetch entries and to functions you explicitly cache with tags (unstable_cache today) — a raw ORM query with no caching wrapper is invisible to the whole mechanism.

// lib/data/products.ts
export async function getProduct(id: string) {
  const res = await fetch(`${CMS_URL}/products/${id}`, {
    next: { tags: [`catalog:product:${id}`, 'catalog:products'] },
  });
  return res.json();
}

Taxonomy: entity, collection, bounded context

Most invalidation incidents trace back to one missing design decision: nobody asked “when X changes, which surfaces must update?” — before the first tag was written. These three species give you the vocabulary to answer it.

Three tag species cover almost everything. An entity tag — catalog:product:42 — names one row’s truth; it belongs on every fetch that returns that entity’s data. A collection tag — catalog:products — names membership and ordering: any fetch whose result would change when a product is created, deleted, or re-ranked carries it. And composite pages carry several: the home page might hold catalog:products, cms:page:home, and pricing:campaign:summer. The prefix is not decoration — it is the bounded context, and the naming convention is architecture: catalog:, cart:, cms:, pricing: mirror team ownership, make collisions impossible, and make grep answer “who can purge what.” The design test for any tag is one question: when X changes, exactly which surfaces must re-render? If you cannot answer it, the tag is not designed yet.

The two failure modes are symmetric. Over-invalidation — the Hook’s global cms tag — means every edit purges everything: hit ratio collapses, regeneration storms hammer origins precisely when traffic is present, and rate-limited upstreams turn a purge into an outage. Under-invalidation — entity tags only — means correctness bugs with business consequences: the price changed, the product page says so, and the category listing quotes the old number for hours. Wrong prices have refund and legal weight, not just aesthetic weight. The working heuristic: detail surfaces get the entity tag, every list-shaped fetch gets a collection tag, and write paths that change membership-relevant fields must emit both.

Webhooks → tags: the mapping table is code

The CMS does not speak tags; it speaks events. The translation lives in one route handler, and writing it as a literal mapping table is the difference between an invalidation policy you can review and one you reverse-engineer during incidents. Two non-negotiables around it: verify the webhook signature — an unauthenticated revalidate endpoint is a free denial-of-service lever, one curl loop from a cold cache — and make unknown event types loud (log and alert) instead of silently dropping or, worse, falling back to a global purge.

// app/api/webhooks/cms/route.ts
import { revalidateTag } from 'next/cache';
import { NextResponse } from 'next/server';
import { verifySignature } from '~/lib/webhooks';

const TAG_MAP: Record<string, (p: Record<string, string>) => string[]> = {
  'product.updated': (p) => [`catalog:product:${p.id}`],
  'product.priced':  (p) => [`catalog:product:${p.id}`, 'catalog:products'],
  'product.created': ()  => ['catalog:products'],
  'page.published':  (p) => [`cms:page:${p.slug}`],
};

export async function POST(req: Request) {
  const event = await verifySignature(req); // 401 on failure — purge is a privilege
  const toTags = TAG_MAP[event.type];
  if (!toTags) return NextResponse.json({ error: 'unmapped event' }, { status: 422 });
  const tags = toTags(event.payload);
  tags.forEach((t) => revalidateTag(t));
  return NextResponse.json({ revalidated: tags });
}

Read the table as policy: a content edit touches one entity; a price change touches the entity and the collections that display prices; a creation touches only collections (no entity page is cached yet). When the nightly price import updates 2,000 products, the mapping emits 2,000 entity tags plus one collection tag — detail pages refresh lazily as visited, listings refresh once. That is the storm-free shape.

The newer model, and how to test the one you have

A newer direction exists and deserves an honest label: the 'use cache' directive with cacheTag() and cacheLife() lets any function or component become a cached, taggable unit — DB queries included, no fetch required. As of now it sits behind experimental flags on canary builds; learn its shape, but build on the stable path — fetch tags plus unstable_cache for non-fetch reads — and isolate tagging inside your data layer so the migration later is a wrapper swap, not a rewrite.

Whatever the mechanism, invalidation is testable, and the test is a staging checklist with both assertions: after firing a product.priced fixture webhook, the product page MUST change, the category listing MUST change — and the about page MUST NOT (watch the cache-status response header flip MISS/STALE on the first two and stay HIT on the third). The must-not-change control is the assertion teams forget, and it is the only automated detector of over-invalidation: hit ratio graphs tell you a week later; the control page tells you in CI.