Gareth Wilson Gareth Wilson

Guide to Cerebrum Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationOne postbackWebhookUrl per integration
PortalSvix webhook portal, on request (subscriptions, logs, replay)
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature, with svix-id and svix-timestamp
SecretOne per webhook, from the Svix portal
BodyJSON
Event routingBody field event
Response windowAny 2xx within 30 seconds. 3xx counts as a failure
RetriesImmediately, then 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h, then dropped
Example bodyNot published, only a JSON Schema
Source IPsNot published

Events and payloads

EventGroupWhat the name indicates
ORDER_STATUS_CHANGEOrderAn order's status changed
ORDER_SCORE_CHANGEOrderAn order's score changed
ORDER_CUSTOM_SCORE_CHANGEOrderAn order's custom score changed
ORDER_DISPUTE_RESOLVEDOrderA dispute on an order was resolved
VOUCHER_STARTEDVoucher (vID)A voucher was started
VOUCHER_REDEEMEDVoucher (vID)A voucher was redeemed
VOUCHER_EXPIREDVoucher (vID)A voucher expired
MONITORING_REPORT_GENERATEDMonitoringA monitoring report was generated
BEAM_INPUT_CREATEDBeamA 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:

FieldDescription
idID of the object the event concerns
idTypeWhat kind of ID id is
additionalMetadataAdditional metadata
eventEvent type, required (one of the values above)
eventDateWhen the event occurred
svixAppIdSvix application ID
metadataEvent 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:

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


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.