A server-rendered Next.js site backed by a .NET API usually calls that API on every page view, even when the content hasn't changed in days. I wanted static-file speed with CMS-level freshness and no rebuilds. This POC proves it with tag-based on-demand ISR (Incremental Static Regeneration), triggered by webhooks from .NET.

#1. The Architecture

Diagram
.NET Core API ──▶ Next.js (build) ──▶ static HTML cache ──▶ users (no API call)
      │                                      ▲
      └──── POST /api/revalidate ────────────┘
          (fired by .NET the instant content changes)
  • Every content page (/[slug]) tags its fetch with page-{slug}. The home listing uses all-pages.
  • After every create, update or delete, .NET sends a signed webhook naming exactly which tags to invalidate.
  • The revalidate route checks a shared secret (401 otherwise) and expires only those tags.

#2. What Actually Happens, Request by Request

Steady state. /home is prerendered at build time. I hit it five times against a production server and the .NET log didn't grow by a single line. Zero backend calls.

An editor saves. .NET updates the record, then fires a webhook: { slug: "home", listingChanged: false }. Next.js marks page-home expired. Nothing is fetched yet.

The next visitor. That one request does a single live fetch, renders fresh HTML and re-caches it. Every visitor after that gets the cached page again. That's one backend call per content change, not one per visitor.

#3. New Pages and Deleted Pages

generateStaticParams() only knows slugs that existed at build time. Two small pieces cover the rest:

  • export const dynamicParams = true lets an unknown slug render on demand (then cache) instead of returning a 404.
  • The backend checks whether the slug existed before writing. For creates and deletes it sets listingChanged: true, which also expires all-pages, so the new page appears in the navigation.
Deletes surfaced a real bug

A missing page threw a raw error, and Next.js turned that into a 500. The fix is to treat an API 404 as "not found", return null and call notFound(). An API that's actually broken should still throw and surface as a 500.

#4. Trap #1: Dev Mode Lies About Caching

next dev doesn't honour the fetch cache the way production does. I disabled the webhook entirely, edited content in .NET, and the dev server still showed the change instantly. That makes it look as if revalidation isn't needed. Only next build && next start shows real caching.

Always validate this pattern against a production build.

#5. Trap #2: Next.js 16 Changed revalidateTag

The single-argument revalidateTag(tag) from most tutorials is deprecated in Next.js 16. It now takes a second argument:

TypeScript
// expire immediately: what a synchronous "content saved" webhook wants
revalidateTag('page-home', { expire: 0 });

// stale-while-revalidate semantics
revalidateTag('page-home', 'max');
Check the bundled docs

create-next-app@latest installed a version far newer than the tutorials assume. When an API behaves oddly, check the docs bundled in node_modules/next/dist/docs/ before trusting remembered examples.

#6. Takeaways

  • Tag-based ISR gives static-site cost with CMS freshness, and the backend decides exactly what goes stale.
  • Fire the webhook from the write path, and sign it.
  • Handle "created" and "deleted" explicitly. They're the cases that break listings and error pages.
  • Test caching behaviour only against production builds.