Docs

Console: Webhooks

Endpoints, events, delivery log and replay.

Webhooks let the rest of your stack react the moment someone changes their mind — suppress a contact in your ESP the second they withdraw, sync a CRM tag, trigger a re-personalization job — without polling the API.

Register an endpoint with an https:// URL, an environment and a list of events. The signing secret is shown once. For local development, expose your receiver through an HTTPS tunnel (ngrok, cloudflared…).

Events

An endpoint subscribes to any of these families of events. The full list, with when each one fires and what its data carries, is in Webhooks: payloads & signature.

Consent — consent.granted · consent.updated · consent.withdrawn · consent.expired
Re-consent — reconsent.required
Preferences — preference.updated and the double opt-in events (preference.confirmation_requested, preference.confirmed, preference.confirmation_email_sent, preference.confirmation_email_failed)
Subjects — subject.merged · subject.erased
Cookies — cookie.scan_completed
Data requests — the dsar.* verification and identity-document events

reconsent.required fires only when a consent expires (an expiry policy flipping a grant to EXPIRED). Publishing a purpose version as Requires re-consent does not emit it — check needsReconsent when you read the subject’s state, or run a re-consent campaign.

Deliveries

Each delivery is signed HMAC-SHA256 (x-croombit-signature: t=…,v1=… header) with timestamp anti-replay. Failures are retried 8 times over about 3 days (1 min → 24 h). From the delivery log you can replay any of them. See Webhooks: payloads & signature for a working receiver and the verification steps.

The Test button on an endpoint sends a synthetic test.ping event, signed like a real one, so you can confirm your URL and secret work end to end. It is not a subscribable event.

The signing secret

The whsec_… secret is shown once, when the endpoint is created — copy it into your secret manager then. To replace it, use Rotate secret on the endpoint: pick how long the old secret keeps working (from “Revoke now” to 72 hours), and the new one is shown once. Subscriptions and the delivery log are kept.