Caching and refreshing pages

A website built on CMS Orbit should be fast for visitors and show new content as soon as editors publish. Both come from caching: pages are kept and served without asking the CMS, and a webhook tells the website exactly which ones to throw away. This page explains every part of it. The setup itself is steps 6, 10 and 15 of Connect a website.

The caches

From the visitor back to the CMS:

The two that matter are the middle two, and the SDK manages both: it labels every CMS answer with cache tags, and its webhook handler expires the right tags. Next.js then also throws away every rendered page that used an expired answer.

The settings

1export const cms = createCmsClient({2  // …3  cache: { revalidate: 60, tags: true },4})

export const revalidate = 60

Previews are never cached, whatever the settings: calls with preview: true send cache: 'no-store'. GraphQL calls are never cached either.

What to choose: revalidate: 60 with tags: true and a webhook. Publishing shows at once, and if a webhook is ever missed, the page catches up within a minute. Use a longer time, such as 300 or 3600, for a busy website where a few minutes of delay after a missed webhook is acceptable; the webhook still makes publishing immediate.

Cache tags

Every call labels its answer with cms, which every answer has, plus the tags in this table:

<region> is the region the call passed, or the client's defaultRegion, or default if neither is set. <path> is the address exactly as you passed it. The language is not part of the tag, so every language of a page in a region shares one tag.

cacheTags from @bifrost-orbit-cms/sdk builds the same tags in your own code:

1import { cacheTags } from '@bifrost-orbit-cms/sdk'23cacheTags.all                         // 'cms'4cacheTags.page('germany', '/about')   // 'cms:page:germany:/about'5cacheTags.navigation('main')          // 'cms:nav:main'6cacheTags.globals                     // 'cms:global'7cacheTags.global('footer')            // 'cms:global:footer'8cacheTags.lists                       // 'cms:list'9cacheTags.regions                     // 'cms:regions'10cacheTags.sitemap                     // 'cms:sitemap'11cacheTags.popups                      // 'cms:popups'12cacheTags.banners                     // 'cms:banners'13cacheTags.references                  // 'cms:references'

What each change refreshes

The webhook handler turns each message into tags with tagsForEvent(event, data), which you can also import from @bifrost-orbit-cms/sdk/next:

Expiring a tag also expires every rendered page that used an answer with that tag. Changing the main menu therefore rebuilds every page whose layout shows it, on its next visit.

Inside the webhook handler

createRevalidateHandler({ secret }) returns a POST route handler. For each request it:

1. Reads x-orbit-timestamp and x-orbit-signature, and the raw body as text.
2. Computes HMAC-SHA256 of the timestamp, a full stop and the body, keyed with the secret, and compares it with the signature in constant time.
3. Refuses a message more than five minutes away from your server's clock.
4. Parses the body and runs tagsForEvent(event, data).
5. Calls revalidateTag(tag, { expire: 0 }) for each tag, so the next visitor gets fresh content rather than one more stale copy.
6. Answers with the tags it refreshed.

Creating the handler without a secret throws straight away. To keep a build working before the secret is set, create it inside the route, as Connect a website does in step 15.

Choose how expired pages are rebuilt

By default an expired page is rebuilt while the next visitor waits, so they see the new content. To serve the old copy one last time and rebuild in the background instead, pass your own revalidate:

1import { revalidateTag } from 'next/cache'2import { createRevalidateHandler } from '@bifrost-orbit-cms/sdk/next'34export const POST = createRevalidateHandler({5  secret: process.env.CMS_WEBHOOK_SECRET!,6  revalidate: (tag) => revalidateTag(tag, 'max'),7})

The same option lets you do more on each refresh, such as purging your CDN:

1revalidate: (tag) => {2  revalidateTag(tag, { expire: 0 })3  if (tag === 'cms' || tag.startsWith('cms:page:')) void purgeCdn(tag)4},

Refresh more than the SDK does

To change which tags an event refreshes, write the route yourself and reuse tagsForEvent. Verify the signature first, as in Refresh the website when content changes, then:

1import { tagsForEvent } from '@bifrost-orbit-cms/sdk/next'23const tags = tagsForEvent(message.event, message.data)4if (message.event === 'content.published' && message.data.contentType === 'blogPost') tags.push('blog-feed')5tags.forEach((tag) => revalidateTag(tag, { expire: 0 }))

Make sure the tags match

A page is only refreshed if the tag your website used when reading it is the tag the webhook names. The webhook names the page by its region key and its address as the CMS stores it. Check three things:

• Use the region key, not its short code. defaultRegion: 'germany', not 'de'. Both read the same content, but a page read with de is tagged cms:page:de:/about, while the webhook refreshes cms:page:germany:/about. Find the key in Configuration › Environments.
• Always say which region. Without defaultRegion or region, pages are tagged with default, which no webhook names. They only refresh on expiry, or when everything is refreshed.
• Pass the address the CMS stores. It starts with /, has no trailing slash except for the home page /, has no region prefix such as /de, and no query string. Build it from the route's segments: '/' + slug.join('/').

Pages answered by another region's fallback are tagged with the region you asked for, but publishing names the region the page belongs to. They catch up on expiry. To refresh them at once, add those tags in your own revalidate.

Your own fetch calls

Calls you make with fetch or another library are not tagged by the SDK. To have them refreshed by webhooks, label them with the SDK's tags:

1import { cacheTags } from '@bifrost-orbit-cms/sdk'23const response = await fetch(`${process.env.CMS_API_URL}/v1/list?type=blogPost`, {4  headers: { Authorization: `Bearer ${process.env.CMS_PUBLIC_KEY}` },5  next: { revalidate: 60, tags: [cacheTags.all, cacheTags.lists] },6})

With 'use cache' functions, call cacheTag(cacheTags.all, cacheTags.lists) from next/cache inside them.

Refresh by hand

Sometimes you need everything fresh at once, such as after changing the website's code to read content differently. A deploy clears rendered pages, but some hosting keeps CMS answers across deploys. To clear both, add a protected route:

1import { revalidateTag } from 'next/cache'2import { cacheTags } from '@bifrost-orbit-cms/sdk'34export async function POST(request: Request) {5  if (request.headers.get('authorization') !== `Bearer ${process.env.REFRESH_TOKEN}`) {6    return new Response('Unauthorized', { status: 401 })7  }8  const tag = new URL(request.url).searchParams.get('tag') ?? cacheTags.all9  revalidateTag(tag, { expire: 0 })10  return Response.json({ revalidated: [tag] })11}

curl -X POST -H "Authorization: Bearer $REFRESH_TOKEN" "https://www.example.com/api/refresh?tag=cms"

Try it on your computer

Caching only behaves as described in a production build. next dev renders every page on every request, so build and start the website instead:

npm run build && npm run start

Send a signed message yourself

You can call your webhook route without the CMS. Put any secret in .env.local, such as CMS_WEBHOOK_SECRET=whsec_local_test, start the website, then sign and send a message:

1SECRET=whsec_local_test2BODY='{"event":"content.published","sentAt":"2026-10-19T09:30:00.000Z","data":{"url":"/about","region":"germany","contentType":"page"}}'3TS=$(node -e 'console.log(Date.now())')4SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')56curl -i -X POST http://localhost:3000/api/revalidate \7  -H 'Content-Type: application/json' \8  -H "x-orbit-timestamp: $TS" \9  -H "x-orbit-signature: $SIG" \10  --data "$BODY"

The answer is 200 with {"revalidated":["cms:page:germany:/about","cms:list","cms:sitemap","cms:references"]}. Change BODY to try other events, such as {"event":"navigation.changed","sentAt":"…","data":{"key":"main"}}.

Receive real webhooks

The CMS can only call a public https address. Use a tunnelling service, such as Cloudflare Tunnel or ngrok, to give your computer one:

cloudflared tunnel --url http://localhost:3000

Create a webhook for the address it prints plus /api/revalidate, with Environment set to the one your local website reads, and put its secret in .env.local. Delete the webhook when you are done; it switches itself off after 20 failed deliveries anyway.

Several websites and environments

• One webhook per website. A staging website and the live website each need their own webhook, with Environment set to Staging and Production, and each its own secret.
• Several copies of one website. If your website runs on several servers, each keeps its own cache unless they share one. On Vercel and Netlify the cache is shared for you. When hosting yourself, configure a shared cache handler, such as one backed by Redis, or run one copy; see Deploy your website.
• A CDN in front. If your CDN caches HTML, it does not know about Next.js's tags. Give pages a short s-maxage, or purge the CDN from your own revalidate as shown above.

When a page stays out of date

Work down this list:

1. Did the webhook arrive? Open Configuration › Webhooks, then Deliveries in the webhook's ⋯ menu. No row means the webhook is off, for another environment, or the event is not ticked.
2. Was it accepted? A 401 is a wrong secret or a clock more than five minutes out. See Refresh the website when content changes.
3. Which tags did it refresh? Point at the result to see your answer. Compare the page tag with the region and address your website reads.
4. Is the client tagging? cache: { tags: true } must be on the client that reads the page.
5. Is the page read through the client? Your own fetch calls need tags, as above.
6. Is something else caching? A CDN or the browser may hold the old HTML. Check the response headers.
7. Does the region match? See "Make sure the tags match" above.

If you cannot find it, the page still refreshes within revalidate seconds. Troubleshooting your website has more.