Skip to content

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.

Webhooks in Orbit
Headers
x-orbit-timestamp, x-orbit-signature, plus x-orbit-event and x-orbit-delivery
Time in
Milliseconds
Signature
Lowercase hex, no prefix
CMS Orbit webhooks
Headers
x-orbit-timestamp, x-orbit-signature
Time in
Milliseconds
Signature
Lowercase hex, no prefix
Careers Orbit webhooks
Headers
x-orbit-timestamp, x-orbit-signature, plus x-orbit-event and x-orbit-delivery
Time in
Milliseconds
Signature
Lowercase hex, no prefix
Careers Orbit website webhook
Headers
x-orbit-timestamp, x-orbit-signature
Time in
Milliseconds
Signature
Lowercase hex, no prefix
Commerce Orbit webhooks
Headers
Orbit-Signature: t=<time>,v1=<signature>, plus Orbit-Event and Orbit-Webhook-Id
Time in
Seconds, inside the header
Signature
Lowercase hex after v1=

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

  1. Read the raw request body as text, before any JSON parsing. Parsing and encoding it again changes the bytes and breaks the signature.
  2. 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",…}.
  3. 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.
  4. Compare your result with the signature in the header, in constant time, so the time taken doesn't give the signature away.
  5. 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.
  6. Answer 401 if either check fails. Otherwise answer with a 2xx status 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:

HTTP
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

TypeScript
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

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

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.

JavaScript, @bifrost-orbit-cms/sdk 0.12.0 and later
Helper
verifyWebhook({ body, timestamp, signature, secret })
What it gives back
{ 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.
Next.js, @bifrost-orbit-cms/sdk/next
Helper
createRevalidateHandler({ secret })
What it gives back
A whole route handler that checks the message and refreshes the pages' cache tags
PHP, bifrost-orbit/cms-sdk
Helper
Webhook::verify($secret, $timestamp, $body, $signature)
What it gives back
true or false. Webhook::parse($secret, $headers, $body) also gives back event and data, or null.
Swift, CMSOrbit 0.2.0 and later
Helper
CMSWebhook.verify(secret:timestamp:signature:body:)
What it gives back
true or false. CMSWebhook.parse(…) also gives back the message, or nil. Apple platforms only.
Kotlin, com.bifrostorbit:cms-sdk 0.2.0 and later
Helper
CmsWebhook.verify(secret, timestamp, signature, body)
What it gives back
true or false. CmsWebhook.parse(…) also gives back the message, or null.
Careers, @bifrost-orbit-careers/sdk/next
Helper
createRevalidateHandler({ secret })
What it gives back
A route handler for the website webhook that refreshes the job pages
Careers PHP, bifrost-orbit/careers-sdk
Helper
Webhook::verify($secret, $timestamp, $body, $signature)
What it gives back
true or false

In JavaScript:

TypeScript
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:

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:

Swift
import CMSOrbitlet ok = CMSWebhook.verify(secret: secret, timestamp: timestamp, signature: signature, body: body)
Kotlin
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:

HTTP
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

TypeScript
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

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

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 UTC
  • X-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:

TypeScript
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:

CMS Orbit
Answer within
10 seconds
Redirects
Don't redirect: register the final address
Retries
None. A failed message shows in the webhook's Deliveries
Turns itself off
After 20 failures in a row
Careers Orbit webhooks
Answer within
10 seconds
Redirects
Not followed, count as a failure
Retries
After 1, 2, 4, 8, 16, 32 and 64 minutes, 8 tries in all
Turns itself off
After 20 failed deliveries in a row
Careers Orbit website webhook
Answer within
5 seconds
Redirects
Don't redirect: register the final address
Retries
After 2 minutes, then twice as long each time, up to 10 tries
Turns itself off
No
Commerce Orbit
Answer within
10 seconds
Redirects
Not followed, count as a failure
Retries
After 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours, 8 tries in all
Turns itself off
After at least 10 failures over 3 days

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

Every signature is wrong
Likely cause
The body was parsed before the check, a proxy changed it, or the secret is incomplete. Use the raw body and the whole secret, including whsec_.
Every message is too old
Likely cause
Your code treats the time in the wrong unit: x-orbit-timestamp is milliseconds, t= in Orbit-Signature is seconds. Or your server's clock is wrong.
The signature stopped matching after a change in the satellite
Likely cause
Someone made a new signing secret. The old one stops working at once. Copy the new one into your settings.
The same message arrives twice
Likely cause
A retry after a lost answer. Skip it with x-orbit-delivery, Orbit-Webhook-Id or the event's id.

Was this page helpful?

Read next