# Refresh the website when content changes > Create a webhook, receive and verify its signed messages with or without the SDK, and refresh only the pages, menus and sitemaps that changed. Source: https://docs.bifrostorbit.com/cms/developers/webhooks/ ## 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](https://docs.bifrostorbit.com/cms/developers/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**. > **Important:** The secret is shown once. It cannot be seen again later. If you lose it, delete the webhook and create a new one. 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 | On screen | Webhook event | Sent when | | --- | --- | --- | | Page published | `content.published` | A page or entry goes live, or a page goes back to an earlier version | | Page unpublished | `content.unpublished` | A page or entry is taken offline | | Page deleted | `content.deleted` | A page or entry is moved to the bin | | Release published | `release.published` | A release has run | | Menu changed | `navigation.changed` | A menu is created, changed or deleted | **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](https://docs.bifrostorbit.com/cms/developers/events/) for every event and what it carries. ## Receive it with Next.js With the SDK, the handler is two lines: ```ts // app/api/cms-webhook/route.ts 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](https://docs.bifrostorbit.com/cms/developers/caching-and-refresh/) 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: ```http POST /api/cms-webhook HTTP/1.1 Host: www.example.com Content-Type: application/json x-orbit-timestamp: 1792229400412 x-orbit-signature: 5d1f0c6b0e7a… {"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. | Header | Holds | | --- | --- | | `x-orbit-timestamp` | When the message was sent, in milliseconds since 1 January 1970 UTC, as text | | `x-orbit-signature` | The signature, as 64 lowercase hexadecimal characters with no prefix | 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 ```ts import { createHmac, timingSafeEqual } from 'node:crypto' import express from 'express' const app = express() const FIVE_MINUTES = 5 * 60 * 1000 function verify(rawBody: string, timestamp: string, signature: string): boolean { if (!/^\d+$/.test(timestamp)) return false if (Math.abs(Date.now() - Number(timestamp)) > FIVE_MINUTES) return false const expected = createHmac('sha256', process.env.CMS_WEBHOOK_SECRET!) .update(`${timestamp}.${rawBody}`) .digest('hex') return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature)) } app.post('/api/cms-webhook', express.text({ type: 'application/json' }), (req, res) => { const ok = verify(req.body, req.get('x-orbit-timestamp') ?? '', req.get('x-orbit-signature') ?? '') if (!ok) return res.sendStatus(401) const { event, data } = JSON.parse(req.body) res.sendStatus(204) refreshCache(event, data).catch(console.error) }) ``` ### Python ```python import hashlib import hmac import os import time from flask import Flask, request app = Flask(__name__) SECRET = os.environ["CMS_WEBHOOK_SECRET"].encode() FIVE_MINUTES = 5 * 60 * 1000 def verify(raw_body: bytes, timestamp: str, signature: str) -> bool: if not timestamp.isdigit(): return False if abs(time.time() * 1000 - int(timestamp)) > FIVE_MINUTES: return False expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) @app.post("/api/cms-webhook") def cms_webhook(): ok = verify( request.get_data(), request.headers.get("x-orbit-timestamp", ""), request.headers.get("x-orbit-signature", ""), ) if not ok: return "", 401 message = request.get_json() queue_refresh(message["event"], message["data"]) return "", 204 ``` ### PHP ```php