# 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.

Source: https://docs.bifrostorbit.com/orbit/developers/verify-webhooks/

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.

| Sent by | Headers | Time in | Signature |
| --- | --- | --- | --- |
| Webhooks in Orbit | `x-orbit-timestamp`, `x-orbit-signature`, plus `x-orbit-event` and `x-orbit-delivery` | Milliseconds | Lowercase hex, no prefix |
| CMS Orbit webhooks | `x-orbit-timestamp`, `x-orbit-signature` | Milliseconds | Lowercase hex, no prefix |
| Careers Orbit webhooks | `x-orbit-timestamp`, `x-orbit-signature`, plus `x-orbit-event` and `x-orbit-delivery` | Milliseconds | Lowercase hex, no prefix |
| Careers Orbit website webhook | `x-orbit-timestamp`, `x-orbit-signature` | Milliseconds | Lowercase hex, no prefix |
| Commerce Orbit webhooks | `Orbit-Signature: t=<time>,v1=<signature>`, plus `Orbit-Event` and `Orbit-Webhook-Id` | Seconds, inside the header | 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](https://docs.bifrostorbit.com/orbit/developers/orbit-webhooks/).

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.1
Content-Type: application/json
x-orbit-timestamp: 1793607242118
x-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

```ts
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
<?php
function 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 hashlib
import hmac
import time

def 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.

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

In JavaScript:

```ts
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 CMSOrbit

let ok = CMSWebhook.verify(secret: secret, timestamp: timestamp, signature: signature, body: body)
```

```kotlin
import com.bifrostorbit.cms.CmsWebhook

val 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.1
Content-Type: application/json
User-Agent: CommerceOrbit-Webhooks/1
Orbit-Webhook-Id: 6650c0ffee0000000000d1d1
Orbit-Event: commerce.order.paid
Orbit-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

```ts
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
<?php
function 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 hashlib
import hmac
import time

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

```ts
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](https://docs.bifrostorbit.com/careers/everyone/assessments/).

## Answers, retries and turning off

Each satellite waits a different time for your answer and retries differently:

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

| You see | Likely cause |
| --- | --- |
| Every signature is wrong | 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 | 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 | 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 | A retry after a lost answer. Skip it with `x-orbit-delivery`, `Orbit-Webhook-Id` or the event's `id`. |
