ISR Caching & Webhooks

The graphqlFetch Pattern #

All GraphQL requests go through a single graphqlFetch() helper in src/lib/optimizely/client.ts. It applies caching automatically based on context — published ISR by default, no-store for draft/preview, and caller-overridable for fine-grained control.

Graph's Response Cache — A Second Layer #

Two independent cache layers sit between an editor publishing content and a user seeing it. They are bypassed with different mechanisms — and cache: "no-store" in Next.js only skips Layer 1. Graph can still return a stale response from its own CDN cache unless you also add ?cache=false to the endpoint URL.

Bypassing Graph's cache — raw URL vs SDK

// Layer 2: Graph's own CDN cache at cg.optimizely.com
// Bypassed by appending ?cache=false to the endpoint URL.
// Setting cache: "no-store" in Next.js only skips Layer 1 — Graph can still
// return a cached response unless you also pass ?cache=false.

const GATEWAY = process.env.OPTIMIZELY_GRAPH_GATEWAY;
// "https://cg.optimizely.com/content/v2"

// Standard — Graph may return a CDN-cached response:
fetch(`${GATEWAY}`, { method: "POST", ... });

// Bypass Graph cache — always fresh from Graph's data store:
fetch(`${GATEWAY}?cache=false`, { method: "POST", ... });

// SDK methods (getContentByPath, getContent) support { cache: false }
// which adds ?cache=false to the URL automatically:
const client = getClient();
await client.getContentByPath(url, { cache: false });
await client.getContent({ key, version }, { cache: false });

// The catch-all CMS page route (src/app/[[...slug]]/page.tsx) uses both:
export const dynamic = "force-dynamic";  // Layer 1: skip Next.js output cache
// ...
await client.getContentByPath(url, { cache: false });  // Layer 2: skip Graph CDN cache
// Result: every request gets the absolute latest content from Graph's data store.

Webhook Endpoints #

Three webhook routes handle different event sources. All return immediately — cache invalidation is synchronous but page regeneration is lazy (happens on the next request, not inline with the webhook).

The most flexible endpoint. Send a specific path to regenerate one page, or omit it to bust the entire layout cache. Register this in CMS Settings → Events → Content Published. Requires the x-revalidate-secret header.

// POST /api/revalidate
// Header: x-revalidate-secret: <OPTIMIZELY_REVALIDATE_SECRET>
// Body:   { "path": "/about/" }   — or omit path for full-site bust

import { revalidatePath } from "next/cache";

export async function POST(request: NextRequest) {
  const secret = request.headers.get("x-revalidate-secret");
  if (secret !== process.env.OPTIMIZELY_REVALIDATE_SECRET) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
  const { path } = await request.json();
  path ? revalidatePath(path) : revalidatePath("/", "layout");
  return NextResponse.json({ revalidated: true, timestamp: Date.now() });
}

Registered directly with Optimizely Graph (via npm run webhook:register). Graph calls this endpoint for three event types: bulk.completed (sync finished), doc.updated (single item changed), doc.expired (item hit its StopPublish date). No secret required — Graph authenticates with HMAC in production.

// POST /api/webhooks  (registered via: npm run webhook:register)
// Triggered by Optimizely Graph on every content change — no secret required
// (Graph signs requests with HMAC; validate in production)

// Payload shapes:
// { "type": "bulk.completed",  ... }  — Graph finished a content sync
// { "type": "doc.updated",     ... }  — a single item was updated
// { "type": "doc.expired",     ... }  — item reached its StopPublish date

export async function POST(request: NextRequest) {
  const body = await request.json();
  revalidatePath("/", "layout");
  revalidateTag("navigation");          // navigation is the most time-sensitive
  return NextResponse.json({ received: true });
}

A simpler variant of /api/revalidate that always busts the entire layout cache. Use this when you want a single "fire and forget" publish hook with no payload parsing. Register in CMS Settings → Events alongside /api/revalidate.

// POST /api/publish
// Header: x-revalidate-secret: <OPTIMIZELY_REVALIDATE_SECRET>
// Triggered by CMS Settings > Events > "Content Published"

export async function POST(request: NextRequest) {
  // auth check …
  revalidatePath("/", "layout");        // bust every ISR page
  return NextResponse.json({ received: true, timestamp: Date.now() });
}