# Guide to Cerebrum Webhooks: Features and Best Practices

Cerebrum runs background checks and identity verification for employers and platforms. You place orders, issue vID vouchers that candidates redeem to verify themselves, and run ongoing monitoring. Results aren't instant, so Cerebrum's webhooks tell you when an order's status or score changes, a dispute is resolved, a voucher is started, redeemed or expires, or a monitoring report is ready. They let your hiring or onboarding flow move on without polling for results.

## What are Cerebrum webhooks?

Each Cerebrum integration has one `postbackWebhookUrl`. When an event happens, Cerebrum sends a JSON `POST` there with the event name and the ID of the order or voucher it concerns.

Cerebrum hands delivery to Svix. Requests carry `svix-id`, `svix-timestamp` and `svix-signature` headers, retries follow Svix's schedule, and the signing secret, subscription settings, delivery logs and replay all live in a Svix portal that Cerebrum gives you access to on request.

## Cerebrum webhook features

| Feature | Details |
| --- | --- |
| Configuration | One `postbackWebhookUrl` per integration |
| Portal | Svix webhook portal, on request (subscriptions, logs, replay) |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `svix-signature`, with `svix-id` and `svix-timestamp` |
| Secret | One per webhook, from the Svix portal |
| Body | JSON |
| Event routing | Body field `event` |
| Response window | Any `2xx` within 30 seconds. `3xx` counts as a failure |
| Retries | Immediately, then 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h, then dropped |
| Example body | Not published, only a JSON Schema |
| Source IPs | Not published |

## Events and payloads

| Event | Group | What the name indicates |
| --- | --- | --- |
| `ORDER_STATUS_CHANGE` | Order | An order's status changed |
| `ORDER_SCORE_CHANGE` | Order | An order's score changed |
| `ORDER_CUSTOM_SCORE_CHANGE` | Order | An order's custom score changed |
| `ORDER_DISPUTE_RESOLVED` | Order | A dispute on an order was resolved |
| `VOUCHER_STARTED` | Voucher (vID) | A voucher was started |
| `VOUCHER_REDEEMED` | Voucher (vID) | A voucher was redeemed |
| `VOUCHER_EXPIRED` | Voucher (vID) | A voucher expired |
| `MONITORING_REPORT_GENERATED` | Monitoring | A monitoring report was generated |
| `BEAM_INPUT_CREATED` | Beam | A Beam input was created |

The lists in Cerebrum's docs don't fully agree. The payload schema's `event` enum includes `BEAM_INPUT_CREATED`, which isn't on the Event Types page, and leaves out `ORDER_CUSTOM_SCORE_CHANGE`, `ORDER_DISPUTE_RESOLVED` and `VOUCHER_STARTED`, which are. The page about change deltas refers to `order.updated` events, a spelling in neither list. Route on the `event` value you actually receive and acknowledge anything you don't recognise.

The body follows a JSON Schema with `additionalProperties: false`:

| Field | Description |
| --- | --- |
| `id` | ID of the object the event concerns |
| `idType` | What kind of ID `id` is |
| `additionalMetadata` | Additional metadata |
| `event` | Event type, **required** (one of the values above) |
| `eventDate` | When the event occurred |
| `svixAppId` | Svix application ID |
| `metadata` | Event details; `metadata.delta` is a JSON-Patch-style change list on some order updates |

The notification identifies the object rather than carrying the full result. Fetch the order or voucher from the Cerebrum API when you need its details. Cerebrum publishes no complete example body, so check a real delivery in the Svix portal before you write parsing code.

## Setting up Cerebrum webhooks

1. Set your integration's `postbackWebhookUrl` to your handler, for example `https://example.com/webhooks/cerebrum`.
2. Ask Cerebrum for access to the Svix webhook portal.
3. In the portal, choose the event types to receive and copy the signing secret.
4. Store the secret as `CEREBRUM_WEBHOOK_SECRET`.

Cerebrum doesn't print the secret's form. Svix secrets normally start with `whsec_`, and both the function below and Hookdeck's source base64-decode the part after that prefix, so confirm the prefix in the portal.

To receive events through Hookdeck, create a source with the **Cerebrum** type, paste the secret, and set `postbackWebhookUrl` to the source URL. While developing, forward the source with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 cerebrum --path /webhooks/cerebrum

```

## Securing Cerebrum webhooks

Cerebrum suggests the Svix SDK, or manual verification with HMAC-SHA256 if you'd rather not add the dependency. Manually, you sign `<svix-id>.<svix-timestamp>.<raw body>` with the decoded secret and compare the base64 result with every `v1,` entry in `svix-signature`:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The Svix SDK checks the timestamp as well and rejects requests more than five minutes old. With Cerebrum's schedule, that only matters if something else delays the request, but Hookdeck is one such case: it keeps the original `svix-timestamp` on retries and replays and applies no timestamp tolerance itself. The function above leaves the age check out for that reason.

Cerebrum tolerates up to 30 seconds, but there's no reason to call the Cerebrum API inside the request. Store the notification and fetch the order afterwards:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

// inbox.put(svixId, notification) stores the notification and resolves once durable.
function createCerebrumReceiver(inbox) {
  const app = express();
  app.post('/webhooks/cerebrum', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.CEREBRUM_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    const body = parseJsonObject(req.body);
    if (!body) return res.sendStatus(400); // signed, but not a JSON object
    const { id, idType, event, eventDate } = body;
    try {
      await inbox.put(req.headers['svix-id'], { id, idType, event, eventDate });
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(204);
  });
  return app;
}

```

Through a Hookdeck Cerebrum source, a request whose signature doesn't verify is still answered with `200`. Hookdeck flags it as failed verification and doesn't send it on.

> **Make Cerebrum webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies the Svix signature on every order and voucher notification, keeps a history you can search by event, and retries delivery to your onboarding service on your terms.

## Cerebrum webhook limitations and pain points

### Event names you can't fully trust

**The Problem:** A handler built from the docs misses some events or waits for ones that never come.

**Why It Happens:** The Event Types page and the payload schema list different values, and one page uses a dotted `order.updated` name.

**Workarounds:**

* Log every distinct `event` value you receive in the first weeks, and adjust your routing.
* Default unknown values to a generic "fetch the object and re-check" path.

**How Hookdeck Can Help:** Hookdeck's request log lets you search deliveries by body content, so you can list the `event` values Cerebrum has really sent.

### No example payload

**The Problem:** You have to guess what `metadata` holds for each event.

**Why It Happens:** Cerebrum publishes a JSON Schema, not sample bodies, and `metadata` varies by event. `metadata.delta` appears only on some order updates.

**Workarounds:**

* Read deliveries in the Svix portal, or capture a real one, before writing parsers.
* Treat `metadata` as optional and fetch the order from the API for anything you need to rely on.

**How Hookdeck Can Help:** Every delivery to a Hookdeck source is stored with its full body and headers, so real examples build up as soon as traffic starts.

### Redirects count as failures

**The Problem:** Deliveries keep failing even though the endpoint works in a browser.

**Why It Happens:** Only a `2xx` counts as success. A `301` or `302`, for example from HTTP to HTTPS or a missing trailing slash, is treated as a failure and retried.

**Workarounds:**

* Register the exact final URL.

**How Hookdeck Can Help:** A Hookdeck source URL answers `200` directly, and you can see your own service's responses, redirects included, in Hookdeck's delivery attempts.

### Events are dropped after the last retry

**The Problem:** An outage longer than about a day loses notifications.

**Why It Happens:** The Svix schedule ends after the second 10-hour wait, roughly 28 hours after the first attempt, and the message is dropped.

**Workarounds:**

* Replay failed messages from the Svix portal once your endpoint recovers.
* Poll open orders periodically so a lost notification only delays an update.

**How Hookdeck Can Help:** Hookdeck receives every notification as soon as Cerebrum sends it, so the 28-hour clock never starts. Your service gets the event whenever it comes back, with [retries](/docs/retries) you control.

## Best practices

### Deduplicate on `svix-id`

Every retry of a message has the same `svix-id`. Record it before acting, so a retried `ORDER_STATUS_CHANGE` doesn't move a candidate twice. The approach is described in [our webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency).

### Fetch the order before deciding

Use the notification as a trigger and read the order's current status and score from the API. That protects you from out-of-order delivery and from incomplete `metadata`.

### Keep results out of logs

Background-check outcomes are sensitive personal data. Log the `svix-id`, `event` and object `id`, not the body.

### Act on voucher expiry

`VOUCHER_EXPIRED` means a candidate didn't finish verification in time. Re-issue a voucher or remind the candidate before your onboarding deadline.

## Conclusion

Cerebrum sends small notifications that name an object for you to fetch, and Svix retries them over a long schedule. Get Svix portal access early, because the documented event lists disagree and real payloads settle the question.

[Hookdeck Event Gateway](https://hookdeck.com) gives you a searchable record of what Cerebrum actually sends and keeps events safe while your service is down. [Set up a free account](https://dashboard.hookdeck.com/signup).