Refresh the website when content changes

What a webhook is for

A webhook is an address on your website that the CMS calls when content changes. Your website then refreshes the pages that changed, so visitors see new content within seconds instead of waiting for a cache to expire.

Each message is a signed POST request with a short JSON body. It names what changed, such as the page /products/hiking-boots in region de, so the website can refresh just that page.

You do not need a webhook for content to appear. Websites set up as in Connect a website refresh their cache every 60 seconds anyway. A webhook makes it immediate.

Your plan sets how many webhooks the organisation can have: 2 on Starter, 20 on Growth, and as many as you need on Enterprise. The Webhooks page shows how many are in use, and New webhook is switched off with the reason once the plan is full. One webhook can listen for every event in a website, so most websites need only one.

Create a webhook

You need the Developer, Administrator or Owner role. Others can see the screen but not change it.

1. Open Configuration › Webhooks and select New webhook.
2. In Name, enter something that says where it goes, such as Website.
3. In Address, enter the full https address of your handler, such as https://www.example.com/api/cms-webhook. Plain http is refused, except for localhost.
4. In Environment, choose Every environment or one environment, such as Production. The webhook only hears about changes in what you choose. Use separate webhooks for a staging site and a live site.
5. Under Events, tick what the website should hear about. Page published, Page unpublished and Menu changed are ticked for you. For a website, also tick Page deleted and Release published.
6. Select Create webhook.
7. Copy the secret from the next dialog, which starts with whsec_, and store it in your website's settings as CMS_WEBHOOK_SECRET. Then select Done.

A webhook cannot be edited. To change its address, events or environment, delete it and create it again. It then gets a new secret.

The events you can choose

Page rolled back, Page promoted and Redirect published are also on the screen. A rollback, and a page promoted into the webhook's environment, such as from Staging to Production, are sent as content.published, so the website refreshes either way. Nothing is sent for a redirect at the moment. See Events and webhooks for every event and what it carries.

Receive it with Next.js

With the SDK, the handler is two lines:

import { createRevalidateHandler } from '@bifrost-orbit-cms/sdk/next'export const POST = createRevalidateHandler({ secret: process.env.CMS_WEBHOOK_SECRET! })

It checks the signature, refuses messages more than five minutes old, and refreshes only the cache tags for what changed. It answers 401 if the check fails and 200 with the refreshed tags otherwise. A test message refreshes nothing.

Tag refresh only works if the client is created with cache: { tags: true }. Caching and refreshing pages explains every cache, which tags each event refreshes, how to test it on your computer and what to check when a page stays out of date.

Receive it without the SDK

Any language can receive webhooks. Each request looks like this:

1POST /api/cms-webhook HTTP/1.12Host: www.example.com3Content-Type: application/json4x-orbit-timestamp: 17922294004125x-orbit-signature: 5d1f0c6b0e7a…67{"event":"content.published","sentAt":"2026-10-17T09:30:00.412Z","data":{"contentId":"6650f1c2a9e4b3d2c1f0ea07","url":"/products/hiking-boots","name":"Hiking boots","locale":"de-DE","region":"germany","version":7}}

Each content event also says its contentType. When a page is published or promoted at a new address, data also has previousUrl, the address it had before, whether or not a redirect was made. Menus and links elsewhere point at the new address from then on, so refresh more than the one page; the SDK's handler refreshes everything.

Publishing a shared section sends a content event with contentType: "sharedSection" and no url. Any page may show the section, so refresh everything; the SDK's handler does from version 0.7.0.

To check a message:

1. Read the raw request body as text, before any JSON parsing. Parsing and re-encoding changes the bytes and breaks the signature.
2. Build the signed string: the timestamp header, a full stop, then the raw body. For example 1792229400412.{"event":"content.published",…}.
3. Compute HMAC-SHA256 of that string, keyed with the webhook secret (the whole value, including whsec_), and write it as lowercase hex.
4. Compare it with x-orbit-signature using a constant-time comparison, so the time taken does not give the signature away.
5. Refuse the message if the timestamp is more than five minutes away from your clock.

Node.js

1import { createHmac, timingSafeEqual } from 'node:crypto'2import express from 'express'34const app = express()5const FIVE_MINUTES = 5 * 60 * 100067function verify(rawBody: string, timestamp: string, signature: string): boolean {8  if (!/^\d+$/.test(timestamp)) return false9  if (Math.abs(Date.now() - Number(timestamp)) > FIVE_MINUTES) return false10  const expected = createHmac('sha256', process.env.CMS_WEBHOOK_SECRET!)11    .update(`${timestamp}.${rawBody}`)12    .digest('hex')13  return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature))14}1516app.post('/api/cms-webhook', express.text({ type: 'application/json' }), (req, res) => {17  const ok = verify(req.body, req.get('x-orbit-timestamp') ?? '', req.get('x-orbit-signature') ?? '')18  if (!ok) return res.sendStatus(401)19  const { event, data } = JSON.parse(req.body)20  res.sendStatus(204)21  refreshCache(event, data).catch(console.error)22})

Python

1import hashlib2import hmac3import os4import time56from flask import Flask, request78app = Flask(__name__)9SECRET = os.environ["CMS_WEBHOOK_SECRET"].encode()10FIVE_MINUTES = 5 * 60 * 1000111213def verify(raw_body: bytes, timestamp: str, signature: str) -> bool:14    if not timestamp.isdigit():15        return False16    if abs(time.time() * 1000 - int(timestamp)) > FIVE_MINUTES:17        return False18    expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()19    return hmac.compare_digest(expected, signature)202122@app.post("/api/cms-webhook")23def cms_webhook():24    ok = verify(25        request.get_data(),26        request.headers.get("x-orbit-timestamp", ""),27        request.headers.get("x-orbit-signature", ""),28    )29    if not ok:30        return "", 40131    message = request.get_json()32    queue_refresh(message["event"], message["data"])33    return "", 204

PHP

1<?php2$body = file_get_contents('php://input');3$timestamp = $_SERVER['HTTP_X_ORBIT_TIMESTAMP'] ?? '';4$signature = $_SERVER['HTTP_X_ORBIT_SIGNATURE'] ?? '';56$expected = hash_hmac('sha256', $timestamp . '.' . $body, getenv('CMS_WEBHOOK_SECRET'));7$fresh = ctype_digit($timestamp) && abs(microtime(true) * 1000 - (int) $timestamp) <= 5 * 60 * 1000;89if (!$fresh || !hash_equals($expected, $signature)) {10    http_response_code(401);11    exit;12}1314$message = json_decode($body, true);15queue_refresh($message['event'], $message['data']);16http_response_code(204);

Connect a website without Next.js shows how to turn each event into a cache refresh in other frameworks.

Respond correctly

• Answer fast. The message is sent while the editor's change is being saved, and each webhook is called in turn. A slow endpoint makes publishing slow for everyone. Check the signature, answer 204, and do slow work, such as rebuilding pages or calling other systems, afterwards or in a queue.
• Answer 2xx for events you ignore. Any other answer counts as a failure, and 20 failures in a row switch the webhook off.
• Answer 401 only for a bad signature or an old timestamp.
• Do not redirect. Register the final address. A redirect usually turns the POST into a GET without a body, so the message is lost.
• Expect the same page more than once. Publishing a page twice sends two messages, and a release sends one per page plus one for the release. Refreshing a cache twice is harmless.

Test it and read the delivery log

Open the ⋯ menu at the end of the webhook's row.

• Send a test sends a webhook.test message straight away, with the webhook's name in data.webhook. A message then shows the answer, such as "Website answered 204", or the reason it failed. Websites using the SDK accept the test and refresh nothing.
• Deliveries shows the latest 50 messages sent to this webhook, newest first. Each row has the Event, the Result and When it was sent. The result is the status code your endpoint answered, or No answer if it could not be reached. Failures are shown in red. Point at a failed result to see why it failed.

The list of webhooks also shows each one's Last delivery, and how many failures in a row it has had, if any.

A test is sent whatever the webhook's Environment, and even when the webhook is switched off.

Retries and failures

Each message is sent once, at the moment of the change. If it fails, the failure is recorded in Deliveries, but the message is not sent again.

• After 20 failures in a row, the webhook is switched off so it cannot slow publishing down. Its On switch turns off. Tests count towards the 20.
• Any successful delivery, including a test, sets the count back to zero.
• While a webhook is off, nothing is sent to it and nothing is saved up for later.

When your endpoint has been down:

1. Fix the endpoint.
2. Select Send a test and check it answers 2xx.
3. Turn the On switch back on. This also sets the failure count to zero.
4. Bring the website up to date. Changes made while it was down were not sent, so clear the website's cache or wait for it to expire. With revalidate: 60 that takes at most a minute.

Secure it

• Always check the signature. Anyone can find your webhook address. Only the CMS knows the secret.
• Refuse old timestamps. Rejecting anything more than five minutes from your clock stops someone replaying a message they captured. Keep your server's clock in sync.
• Use HTTPS. The CMS refuses plain http addresses, except localhost.
• Keep the secret out of code. Store it as an environment variable or in a secrets store, and never log it.

To try webhooks from your own computer, use a tunnelling service that gives your machine a public https address, and register that address.

Change the secret

Change it when someone who knew it leaves, or if it may have leaked. Webhooks cannot be edited, so swap in a new one:

1. Add a second handler on your website, such as /api/cms-webhook-new, that reads a new setting, such as CMS_WEBHOOK_SECRET_NEW.
2. Create a new webhook for that address with the same events and environment, and store its secret in the new setting.
3. Send a test and check Deliveries.
4. Delete the old webhook, then remove the old handler and setting.

While both webhooks exist, each change is sent to both. That is harmless.

Troubleshooting