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_CHANGEorVOUCHER_REDEEMEDevents? - Why is my Cerebrum
svix-signatureverification failing? - Why are Hookdeck retries of Cerebrum webhooks rejected after 5 minutes?
Verification (core)
| Header | Value |
|---|---|
svix-id | Unique message ID, the same on every retry |
svix-timestamp | Unix seconds of this delivery attempt |
svix-signature | One 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_ (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:
| Field | Notes |
|---|---|
event | Event type, required (see below) |
id, idType | The object the event is about and what kind of ID it is |
eventDate | When the event happened |
svixAppId, additionalMetadata | Svix application ID and extra metadata |
metadata | Event 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):
| Event | Group |
|---|---|
ORDER_STATUS_CHANGE | Order |
ORDER_SCORE_CHANGE | Order |
ORDER_ | Order |
ORDER_DISPUTE_RESOLVED | Order |
VOUCHER_STARTED | Voucher (vID) |
VOUCHER_REDEEMED | Voucher (vID) |
VOUCHER_EXPIRED | Voucher (vID) |
MONITORING_ | Monitoring |
BEAM_INPUT_CREATED | Beam |
Cerebrum's delta page also mentions
order.updated, a name that appears in neither event list. See references/overview.md.
Delivery Semantics
- Any
2xxwithin 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
400or401for 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
- references/overview.md - Events, payload fields, delivery and retries
- references/setup.md -
postbackWebhookUrl, Svix Portal, signing secret - references/verification.md - Library and manual verification, header fallback, gotchas, debugging