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
.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 withpage-{slug}. The home listing usesall-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 = truelets 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 expiresall-pages, so the new page appears in the navigation.
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.
#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:
// expire immediately: what a synchronous "content saved" webhook wants
revalidateTag('page-home', { expire: 0 });
// stale-while-revalidate semantics
revalidateTag('page-home', 'max');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.