Agent skill

Cerebrum Webhooks Skill

Receive and verify Cerebrum (cerebrum.com) background-check and identity verification webhooks, delivered through Svix. Use when setting up a Cerebrum postbackWebhookUrl handler, getting the whsec_ signing secret, debugging svix-id / svix-timestamp / svix-signature verification, or handling events like ORDER_STATUS_CHANGE, ORDER_SCORE_CHANGE, ORDER_DISPUTE_RESOLVED, VOUCHER_REDEEMED and MONITORING_REPORT_GENERATED.

Install this skill

npx skills add hookdeck/webhook-skills --skill cerebrum-webhooks


Cerebrum is a background-check and identity-verification (vID / vouchers) API. It POSTs order, voucher and monitoring notifications to the postbackWebhookUrl of your integration. Delivery, signing and the webhook portal are provided by Svix, so every webhook carries svix-id, svix-timestamp and svix-signature headers (Standard Webhooks).

When to Use This Skill

  • How do I receive Cerebrum webhooks?
  • How do I verify a Cerebrum webhook signature?
  • Where do I get the Cerebrum webhook signing secret?
  • How do I handle ORDER_STATUS_CHANGE, ORDER_SCORE_CHANGE or VOUCHER_REDEEMED events?
  • Why is my Cerebrum svix-signature verification failing?
  • Why are Hookdeck retries of Cerebrum webhooks rejected after 5 minutes?

Verification (core)

HeaderValue
svix-idUnique message ID, the same on every retry
svix-timestampUnix seconds of this delivery attempt
svix-signatureOne or more space-separated v1,<base64 HMAC-SHA256> entries

Signed content is {svix-id}.{svix-timestamp}.{raw body}. The key is the base64-decoded part of the secret after whsec_. The same values may arrive as webhook-id, webhook-timestamp and webhook-signature; read svix-* and fall back to webhook-* when svix-id is absent. Use the official svix library (npm, PyPI):

import { Webhook } from 'svix';

// rawBody: exact request body string, NOT re-serialised JSON
function verify(rawBody, h /* header getter */, secret = process.env.CEREBRUM_WEBHOOK_SECRET) {
  const p = h('svix-id') ? 'svix' : 'webhook';
  const headers = { 'svix-id': h(`${p}-id`), 'svix-timestamp': h(`${p}-timestamp`),
                    'svix-signature': h(`${p}-signature`) };
  if (Object.values(headers).some((v) => !v)) throw new Error('missing headers');
  new Webhook(secret).verify(rawBody, headers); // throws on a bad signature or old timestamp
  return JSON.parse(rawBody);                   // parse only after it passes
}

Python: from svix.webhooks import Webhook, then Webhook(secret).verify(raw_body, headers) (returns the parsed payload).

Timestamp window. The library always rejects timestamps more than 5 minutes from now. Hookdeck retries and replays resend the original timestamp, so a retry later than 5 minutes after the original delivery fails verification. If you receive through Hookdeck, use the manual verifier in references/verification.md, where the window can be dropped or widened.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Payload

The JSON body (schema has additionalProperties: false) has these fields:

FieldNotes
eventEvent type, required (see below)
id, idTypeThe object the event is about and what kind of ID it is
eventDateWhen the event happened
svixAppId, additionalMetadataSvix application ID and extra metadata
metadataEvent details. metadata.delta is a JSON-Patch-style change list on some order updates

Cerebrum publishes no example body, so check a real delivery in the Svix Portal. Dedupe on the svix-id header.

Common Event Types

The event field holds one of 9 documented values (the list may not be exhaustive, so acknowledge unknown ones):

EventGroup
ORDER_STATUS_CHANGEOrder
ORDER_SCORE_CHANGEOrder
ORDER_CUSTOM_SCORE_CHANGEOrder
ORDER_DISPUTE_RESOLVEDOrder
VOUCHER_STARTEDVoucher (vID)
VOUCHER_REDEEMEDVoucher (vID)
VOUCHER_EXPIREDVoucher (vID)
MONITORING_REPORT_GENERATEDMonitoring
BEAM_INPUT_CREATEDBeam

Cerebrum's delta page also mentions order.updated, a name that appears in neither event list. See references/overview.md.

Delivery Semantics

  • Any 2xx within 30 seconds succeeds. Anything else (3xx included) or a timeout is retried: immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, then dropped.
  • Return 400 or 401 for a missing header or a bad signature. Enqueue the event and process it asynchronously.
  • No challenge or handshake.

Environment Variables

CEREBRUM_WEBHOOK_SECRET=whsec_xxxxx   # full value including whsec_; handlers fail closed (500) without it

Cerebrum prints no secret value in its docs. The secret comes from the Svix Portal that Cerebrum provides on request; Svix's default form is whsec_<base64>.

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 cerebrum --path /webhooks/cerebrum

Set the URL it prints as your integration's postbackWebhookUrl.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →