Next.js Revalidation on Vercel: Invalidate Public Data Safely

Published

Jul 14, 2026

Updated

Jul 14, 2026

Reading time

12 min read

Time-based caching is a useful fallback, but Acme Shop needs its catalog to refresh after a product is published. In Next.js 16's fetch-based caching model, tags attach an invalidation target to cached data. A protected Route Handler can then map one known publishing event to those known targets. The safe design is allowlisted, authenticated, observable, and preview-tested.

Map one event to tags and paths

Tag data by ownership, not by whichever component currently displays it. Acme Shop uses one collection tag plus one stable product tag. The webhook maps the known product.published event to literal paths; it never accepts a caller-supplied tag or path.

revalidateTag applies to every cached use of a tag. revalidatePath applies to a specific route. Use both here because the event changes shared catalog data and two known rendered paths.

Attach the tags to public fetches

Make the data cache policy explicit. The one-hour interval is a fallback if a publishing event fails; it is not a promise that data remains stale for exactly one hour.

// lib/acme-shop/products.ts
export async function getProducts() {
  const response = await fetch("https://catalog.acme-shop.example/v1/products", {
    cache: "force-cache",
    next: { revalidate: 3600, tags: ["acme-shop:catalog"] },
  })

  if (!response.ok) throw new Error("Products are unavailable")
  return response.json()
}

export async function getProduct(slug: string) {
  const response = await fetch(`https://catalog.acme-shop.example/v1/products/${slug}`, {
    cache: "force-cache",
    next: { revalidate: 3600, tags: ["acme-shop:catalog", `acme-shop:product:${slug}`] },
  })

  if (!response.ok) throw new Error("Product is unavailable")
  return response.json()
}

Tags are case-sensitive and each tag must be no more than 256 characters. Do not use this fetch pattern for data that changes by session, authorization, cart, or user entitlement.

Add an authenticated, allowlisted webhook

The Route Handler rejects missing credentials, malformed JSON, unknown event types, and unsafe slugs before it calls a revalidation primitive. It returns only non-sensitive diagnostic values.

// app/api/revalidate-products/route.ts
import { revalidatePath, revalidateTag } from "next/cache"
import type { NextRequest } from "next/server"

type ProductEvent = { type: "product.published"; slug: string }

function isProductEvent(value: unknown): value is ProductEvent {
  if (!value || typeof value !== "object") return false
  const event = value as Record<string, unknown>
  return event.type === "product.published" &&
    typeof event.slug === "string" && /^[a-z0-9-]+$/.test(event.slug)
}

export async function POST(request: NextRequest) {
  const expected = process.env.ACME_SHOP_REVALIDATE_SECRET
  if (!expected || request.headers.get("authorization") !== `Bearer ${expected}`) {
    return Response.json({ error: "Unauthorized" }, { status: 401 })
  }

  let body: unknown
  try {
    body = await request.json()
  } catch {
    return Response.json({ error: "Invalid JSON" }, { status: 400 })
  }

  if (!isProductEvent(body)) {
    return Response.json({ error: "Unsupported event" }, { status: 400 })
  }

  const productTag = `acme-shop:product:${body.slug}`
  const productPath = `/shop/${body.slug}`
  revalidateTag("acme-shop:catalog", "max")
  revalidateTag(productTag, "max")
  revalidatePath("/shop")
  revalidatePath(productPath)

  return Response.json({
    revalidated: true,
    slug: body.slug,
    tags: ["acme-shop:catalog", productTag],
    paths: ["/shop", productPath],
  })
}

The one-argument revalidateTag(tag) form is deprecated in Next.js 16. With the recommended "max" profile, revalidateTag marks tagged entries stale; it does not eagerly regenerate every page or guarantee the immediately following visitor sees fresh content.

Test valid, invalid, and repeated delivery on preview

Set the secret in the preview environment, configure the publisher to call only the preview URL, and use a shell variable rather than putting a secret literal in the command or shell history.

curl -sS -i -X POST https://acme-shop-preview.example/api/revalidate-products \
  -H "Authorization: Bearer $ACME_SHOP_REVALIDATE_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"type":"product.published","slug":"solar-pack"}'

HTTP/2 200
content-type: application/json

{"revalidated":true,"slug":"solar-pack","tags":["acme-shop:catalog","acme-shop:product:solar-pack"],"paths":["/shop","/shop/solar-pack"]}

HTTP/2 400
content-type: application/json

{"error":"Unsupported event"}

HTTP/2 200
content-type: application/json

{"revalidated":true,"slug":"solar-pack","tags":["acme-shop:catalog","acme-shop:product:solar-pack"],"paths":["/shop","/shop/solar-pack"]}

Validate stale-while-revalidate timing

Use a public product revision such as productRevision: "18" in preview. Capture the collection and product bodies before publication, publish revision 19, trigger the webhook once, and request each URL twice.

curl -sS https://acme-shop-preview.example/shop
curl -sS https://acme-shop-preview.example/shop/solar-pack

The timing is intentionally availability-oriented, not read-your-own-write behavior. If the user who made a mutation must immediately see it, use updateTag in a Server Action rather than turning a public webhook into a synchronous global refresh.

Promote and recover safely

After preview passes, add the same secret to production without exposing it to client code, point the trusted sender at the healthy production deployment, and run one controlled update for solar-pack. Monitor webhook failures, upstream errors, revalidation failures, and stale-content reports.

If a bad event or code change reaches production, stop the sender or disable its event first. Correct the source record, restore the approved deployment if necessary, then deliver one known event and validate the collection and product body twice. Do not start with a broad CDN purge: it cannot correct a bad source record or a faulty tag/path map.

# Run only after approval when an immediate deployment rollback is required.
vercel rollback https://acme-shop-known-good.example

Troubleshooting

Related guides

• Model public and private cache boundaries
• Debug Next.js caching on Vercel

Authoritative references

• Next.js revalidateTag
• Next.js revalidatePath
• Next.js caching and revalidation
• Vercel caching overview