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_ | 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_ | 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_, 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
- Set your integration's
postbackWebhookUrlto your handler, for examplehttps://example.com/webhooks/cerebrum. - Ask Cerebrum for access to the Svix webhook portal.
- In the portal, choose the event types to receive and copy the signing secret.
- 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:
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:
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:
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 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
eventvalue 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
metadataas 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 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.
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 gives you a searchable record of what Cerebrum actually sends and keeps events safe while your service is down. Set up a free account.