Verify webhooks from Bifröst Orbit
Every signature Bifröst Orbit uses, with code to check each in JavaScript, PHP and Python, the SDK helpers that do it for you, and how retries and time limits differ between satellites.
Reference10 min read
CMS, Careers and Commerce Orbit sign every webhook they send, so you can tell it came from Bifröst Orbit and wasn't changed on the way. All of them use HMAC-SHA256 with your webhook's signing secret, over the time it was sent, a full stop and the raw body. They differ in the headers and in the unit of time.
x-orbit-timestamp, x-orbit-signature, plus x-orbit-event and x-orbit-deliveryx-orbit-timestamp, x-orbit-signaturex-orbit-timestamp, x-orbit-signature, plus x-orbit-event and x-orbit-deliveryx-orbit-timestamp, x-orbit-signatureOrbit-Signature: t=<time>,v1=<signature>, plus Orbit-Event and Orbit-Webhook-Idv1=The first four use the same check, below as the x-orbit signature. Commerce Orbit's is below as the Orbit-Signature header.
Travel, Booking, Presence and Insights Orbit have no webhooks of their own. Their events reach your systems through webhooks in Orbit.
One more signature goes the other way: assessment tools sign the results they send to Careers Orbit. See Sign assessment results for Careers Orbit below.
How to check any of them
- Read the raw request body as text, before any JSON parsing. Parsing and encoding it again changes the bytes and breaks the signature.
- Take the time from the header, and build the signed text: the time, a full stop, then the body. For example
1793607242118.{"event":"content.published",…}. - Work out the HMAC-SHA256 of that text, with the whole signing secret as the key, and write it as lowercase hex. The secret starts with
whsec_: keep the prefix, it is part of the key. - Compare your result with the signature in the header, in constant time, so the time taken doesn't give the signature away.
- Refuse the message if the time is more than five minutes away from your clock. That stops someone replaying a message they captured. Keep your server's clock in sync.
- Answer
401if either check fails. Otherwise answer with a2xxstatus at once, and do slow work afterwards.
Every satellite's own checks and SDK helpers use the same five minutes.
The x-orbit signature
From CMS Orbit and Careers Orbit:
POST /api/cms-webhook HTTP/1.1Content-Type: application/jsonx-orbit-timestamp: 1793607242118x-orbit-signature: 5d1f0c6b0e7a…{"event":"content.published","sentAt":"2026-11-02T09:14:02.118Z","data":{…}}x-orbit-timestamp is in milliseconds since 1 January 1970 UTC. x-orbit-signature is 64 lowercase hexadecimal characters.
JavaScript
import { createHmac, timingSafeEqual } from 'node:crypto'export function verifyOrbit(secret: string, timestamp: string, body: string, signature: string): boolean { if (!/^\d+$/.test(timestamp)) return false if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex') return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature))}// In a route handler that receives a Request:export async function POST(request: Request): Promise<Response> { const body = await request.text() const ok = verifyOrbit( process.env.ORBIT_WEBHOOK_SECRET!, request.headers.get('x-orbit-timestamp') ?? '', body, request.headers.get('x-orbit-signature') ?? '', ) if (!ok) return new Response(null, { status: 401 }) const message = JSON.parse(body) // Handle message.event and message.data return new Response(null, { status: 204 })}In Express, read the body with express.text({ type: 'application/json' }) so it stays raw.
PHP
<?phpfunction verify_orbit(string $secret, string $timestamp, string $body, string $signature): bool{ if (!ctype_digit($timestamp)) { return false; } if (abs(microtime(true) * 1000 - (int) $timestamp) > 5 * 60 * 1000) { return false; } $expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret); return hash_equals($expected, $signature);}$body = file_get_contents('php://input');$ok = verify_orbit( getenv('ORBIT_WEBHOOK_SECRET'), $_SERVER['HTTP_X_ORBIT_TIMESTAMP'] ?? '', $body, $_SERVER['HTTP_X_ORBIT_SIGNATURE'] ?? '');if (!$ok) { http_response_code(401); exit;}$message = json_decode($body, true);http_response_code(204);Python
import hashlibimport hmacimport timedef verify_orbit(secret: str, timestamp: str, body: bytes, signature: str) -> bool: if not timestamp.isdigit(): return False if abs(time.time() * 1000 - int(timestamp)) > 5 * 60 * 1000: return False expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)Pass the body as bytes, as it arrived: request.get_data() in Flask, await request.body() in FastAPI, request.body in Django.
With the SDKs
The SDKs check the x-orbit signature and the five minutes for you.
@bifrost-orbit-cms/sdk 0.12.0 and laterverifyWebhook({ body, timestamp, signature, secret }){ valid: true, event, data, tags }, or { valid: false, reason } with 'signature' or 'expired'. Throws if secret is empty. Runs on Node.js 20 and later, Bun, Deno and Workers.@bifrost-orbit-cms/sdk/nextcreateRevalidateHandler({ secret })bifrost-orbit/cms-sdkWebhook::verify($secret, $timestamp, $body, $signature)true or false. Webhook::parse($secret, $headers, $body) also gives back event and data, or null.CMSOrbit 0.2.0 and laterCMSWebhook.verify(secret:timestamp:signature:body:)true or false. CMSWebhook.parse(…) also gives back the message, or nil. Apple platforms only.com.bifrostorbit:cms-sdk 0.2.0 and laterCmsWebhook.verify(secret, timestamp, signature, body)true or false. CmsWebhook.parse(…) also gives back the message, or null.@bifrost-orbit-careers/sdk/nextcreateRevalidateHandler({ secret })bifrost-orbit/careers-sdkWebhook::verify($secret, $timestamp, $body, $signature)true or falseIn JavaScript:
import { verifyWebhook } from '@bifrost-orbit-cms/sdk'export async function POST(request: Request): Promise<Response> { const result = await verifyWebhook({ body: await request.text(), timestamp: request.headers.get('x-orbit-timestamp'), signature: request.headers.get('x-orbit-signature'), secret: process.env.CMS_WEBHOOK_SECRET!, }) if (!result.valid) return new Response(null, { status: 401 }) // result.event, result.data and result.tags return new Response(null, { status: 204 })}In PHP:
use BifrostOrbit\Cms\Webhook;$body = file_get_contents('php://input');$message = Webhook::parse(getenv('CMS_WEBHOOK_SECRET'), getallheaders(), $body);if ($message === null) { http_response_code(401); exit;}// $message['event'] and $message['data']In Swift and Kotlin:
import CMSOrbitlet ok = CMSWebhook.verify(secret: secret, timestamp: timestamp, signature: signature, body: body)import com.bifrostorbit.cms.CmsWebhookval ok = CmsWebhook.verify(secret, timestamp, signature, body)The tags and the Next.js handlers are for CMS Orbit's and Careers Orbit's website messages. For a Careers Orbit webhook to your own systems, use the plain check above or the PHP SDK's Webhook::verify: the signature is the same.
The Orbit-Signature header
From Commerce Orbit:
POST /hooks/commerce HTTP/1.1Content-Type: application/jsonUser-Agent: CommerceOrbit-Webhooks/1Orbit-Webhook-Id: 6650c0ffee0000000000d1d1Orbit-Event: commerce.order.paidOrbit-Signature: t=1793607242,v1=9b2e44c1a0…{"id":"1f6c6a52-…","type":"commerce.order.paid","createdAt":"2026-11-02T09:14:02.118Z","shopId":"…","subject":{…},"data":{…}}t is in seconds since 1 January 1970 UTC, not milliseconds. The signed text is t, a full stop and the raw body, and v1 is its HMAC-SHA256 in lowercase hex. Orbit-Webhook-Id stays the same on every retry of a delivery, so use it to skip repeats.
JavaScript
import { createHmac, timingSafeEqual } from 'node:crypto'export function verifyCommerce(secret: string, header: string, body: string): boolean { const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2))) if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 5 * 60) return false const expected = createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex') return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))}Call it with request.headers.get('orbit-signature') ?? '' and the raw body.
PHP
<?phpfunction verify_commerce(string $secret, string $header, string $body): bool{ $parts = []; foreach (explode(',', $header) as $part) { [$key, $value] = array_pad(explode('=', $part, 2), 2, ''); $parts[$key] = $value; } $time = $parts['t'] ?? ''; $signature = $parts['v1'] ?? ''; if (!ctype_digit($time) || $signature === '' || abs(time() - (int) $time) > 300) { return false; } return hash_equals(hash_hmac('sha256', $time . '.' . $body, $secret), $signature);}$ok = verify_commerce(getenv('COMMERCE_WEBHOOK_SECRET'), $_SERVER['HTTP_ORBIT_SIGNATURE'] ?? '', file_get_contents('php://input'));Python
import hashlibimport hmacimport timedef verify_commerce(secret: str, header: str, body: bytes) -> bool: parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part) stamp, signature = parts.get("t", ""), parts.get("v1", "") if not stamp.isdigit() or not signature or abs(time.time() - int(stamp)) > 300: return False expected = hmac.new(secret.encode(), stamp.encode() + b"." + body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)The SDKs have no helper for this header yet.
Sign assessment results for Careers Orbit
If you connect an assessment or video interview tool to Careers Orbit, your tool sends the results and signs them. The signing secret comes from Make a new signing secret in Careers Orbit's assessment settings. It has no whsec_ prefix.
Send two headers with the POST:
X-Careers-Timestamp: the time in seconds since 1 January 1970 UTCX-Careers-Signature:sha256=followed by the HMAC-SHA256, in lowercase hex, of the timestamp, a full stop and the raw body
Careers Orbit refuses a timestamp more than five minutes from its clock, and answers 401 with invalid_signature for a wrong signature. In JavaScript:
import { createHmac } from 'node:crypto'const body = JSON.stringify({ reference, status: 'completed', score: 8, maxScore: 10 })const timestamp = String(Math.floor(Date.now() / 1000))const signature = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`await fetch(resultAddress, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Careers-Timestamp': timestamp, 'X-Careers-Signature': signature }, body,})In PHP, the signature is 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret); in Python, "sha256=" + hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest(). The body and the fields are in Assessments.
Answers, retries and turning off
Each satellite waits a different time for your answer and retries differently:
Any 2xx answer counts as delivered. Every satellite keeps a delivery log under the webhook, with Send a test to check your address and your signature check: CMS Orbit sends webhook.test, Careers Orbit careers.webhook.test and Commerce Orbit commerce.webhook.test. A test message is signed in the same way.
When the check fails
whsec_.x-orbit-timestamp is milliseconds, t= in Orbit-Signature is seconds. Or your server's clock is wrong.x-orbit-delivery, Orbit-Webhook-Id or the event's id.Was this page helpful?