# Cerebrum Webhooks

[Cerebrum](https://www.cerebrum.com) 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)

| 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`](https://www.npmjs.com/package/svix) library (npm, PyPI):

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/cerebrum-webhooks/references/verification.md), where the window can be dropped or widened.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/cerebrum-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/cerebrum-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/cerebrum-webhooks/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_CUSTOM_SCORE_CHANGE` | Order |
| `ORDER_DISPUTE_RESOLVED` | Order |
| `VOUCHER_STARTED` | Voucher (vID) |
| `VOUCHER_REDEEMED` | Voucher (vID) |
| `VOUCHER_EXPIRED` | Voucher (vID) |
| `MONITORING_REPORT_GENERATED` | 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/cerebrum-webhooks/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

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/cerebrum-webhooks/references/overview.md) - Events, payload fields, delivery and retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/cerebrum-webhooks/references/setup.md) - `postbackWebhookUrl`, Svix Portal, signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/cerebrum-webhooks/references/verification.md) - Library and manual verification, header fallback, gotchas, debugging