Webhooks
Get notified the moment something changes in CMP — a notice gets published, a principal grants or withdraws consent — instead of polling the API. Once a webhook is set up for your org, Bytemonk POSTs a signed JSON payload to your endpoint every time a subscribed event happens. This page covers everything you need to build and verify that receiving endpoint.
Webhook subscriptions (destination URL, event types, signing secret) are configured on the admin side, not through this public API — reach out to your Bytemonk account contact to set one up. You'll be given the signing secret once at setup time; store it the same way you'd store any API credential, since it's what the verification code below uses.
Event types
Notices & consent:
| Event type | Fired when | data fields |
|---|---|---|
notice.published | A DRAFT notice is published (becomes the ACTIVE version) | noticeId, noticeGroupKey, language, version |
consent.granted | A principal grants consent (see Grant Consent) | consentRecordId, principalId, noticeId, method, purposeSelections (map of purposeCode → boolean, reflecting what was actually persisted — e.g. a minor-restricted purpose forced to false server-side even if requested). When the person answered topics or preferences inside a purpose, also choices (map of purposeCode → {topics, preferences}) |
consent.withdrawn | A principal withdraws consent (whole-notice or single-purpose), or a consent record is automatically withdrawn once every granted purpose has exceeded its own retentionPeriodDays | consentRecordId, principalId, noticeId, purposeCode (null for a whole-notice withdrawal, including an automatic retention-triggered one), sourceDomain and consentSurface (which website and screen the consent was originally given on; a withdrawal made on the website or in the preference center carries them), purposeSelections (map of purposeCode → boolean showing every purpose's state after the withdrawal, so you can stop processing exactly the purposes that are now off) |
consent.expired | A consent record is automatically withdrawn by the daily retention sweep because every granted purpose exceeded its retentionPeriodDays — fired alongside consent.withdrawn for the same event, distinguishing a system-driven expiry from a principal's own withdrawal | consentRecordId, principalId, noticeId, purposeCode (always null — the whole record expired), retentionPeriodDays |
consent.renewal_required | A notice is republished with one or more purposes changed/added in a way that requires re-consent (see the requiresReconsent field on purposes) — fired once per publish, not once per affected principal | noticeId, noticeGroupKey, language, version, purposeCodes (the purposes now flagged requiresReconsent), staleConsentCount (how many existing consent records under the previous version are now outdated) |
preference.changed | A grant includes topic or preference answers (see choices). Fired alongside consent.granted | consentRecordId, principalId, noticeId, choices |
consent.unsubscribed_all | A principal withdrew everything they can withdraw in one step (see Unsubscribe from everything) | principalId, noticesWithdrawn, reason (null when none given) |
profile.updated | A principal's profile answers changed. Carries field codes only, never the answers | principalId, fields (the codes that changed) |
consent.snooze_ended | A purpose a principal withdrew "for now" (see snooze) is undecided again because its date passed | consentRecordId, principalId, noticeId, purposeCode, snoozedUntil |
collection_point.submitted | A visitor submitted a collection point's web form | collectionPointCode, version, principalId, consentRecordId (never the answers) |
preference_center.published | A preference center design is published from the dashboard | code, version |
privacy_policy.version_changed | An admin changes the org's privacy policy version label to a different value than before, from the dashboard's CMP Settings page (not something your integration sets directly — the org's privacy policy itself is hosted externally, CMP only tracks a version label for it) | previousVersion, newVersion, staleConsentCount (every currently-ACTIVE consent record across the whole org — this is org-wide, not scoped to one notice) |
Data Principal Requests (DPR):
| Event type | Fired when | data fields |
|---|---|---|
dsr.submitted | A principal submits a DSR request (see Submit a DSR Request) | dsrRequestId, referenceId, principalId, requestType |
dsr.acknowledged | An admin acknowledges a submitted DSR request | dsrRequestId, referenceId, principalId |
dsr.fulfilled | A DSR request is fulfilled — access, correction, or erasure | dsrRequestId, referenceId, principalId, requestType |
dsr.rejected | A DSR request is rejected | dsrRequestId, referenceId, principalId, reason |
dsr.communication_added | A message is added to a DSR's communication thread — by the principal, a DPO, or automatically by Bytemonk itself (e.g. a connected ticketing tool's ticket being created/closed) | requestId, communicationId, authorType ("DPO_USER", "DATA_PRINCIPAL", or "SYSTEM"), principalId |
Grievances:
| Event type | Fired when | data fields |
|---|---|---|
grievance.filed | A principal files a grievance (see File a Grievance) | grievanceId, referenceId, principalId, category |
grievance.acknowledged | An admin acknowledges a filed grievance | grievanceId, referenceId, principalId |
grievance.resolved | A grievance is resolved | grievanceId, referenceId, principalId, resolutionNotes |
grievance.escalated | A grievance is escalated to the Data Protection Board (DPB) | grievanceId, referenceId, principalId |
grievance.assigned | A grievance is assigned to (or unassigned from) a grievance officer | grievanceId, referenceId, officerUserId (null when unassigned) |
grievance.communication_added | A message is added to a grievance's communication thread — by the principal, a DPO/officer, or automatically by Bytemonk itself | requestId, communicationId, authorType ("DPO_USER", "DATA_PRINCIPAL", or "SYSTEM"), principalId |
A subscription can be configured to receive all event types, including ones added later, or just a specific subset — that's part of the setup conversation above, not something you control at request time.
Delivery payload shape
Every delivery is a single POST with this envelope, regardless of event type:
{
"eventType": "consent.granted",
"occurredAt": "2026-07-04T04:50:22.537+00:00",
"data": {
"consentRecordId": 77,
"principalId": 42,
"noticeId": 12,
"method": "WIDGET",
"purposeSelections": { "marketing": false, "analytics": true }
}
}
Alongside the body, every delivery carries these headers:
| Header | Meaning |
|---|---|
X-Bytemonk-Webhook-Signature | t=<unix-timestamp>,v1=<hex-hmac> — see below |
X-Bytemonk-Webhook-Event | Same value as the body's eventType, for routing without parsing JSON first |
X-Bytemonk-Webhook-Delivery | An id unique to this delivery attempt — include it if you contact support about a specific delivery |
Verifying a delivery
The signature proves a request genuinely came from Bytemonk and wasn't tampered with in transit — the same
timestamp + "." + body, HMAC-SHA256 scheme Stripe and GitHub use, so an off-the-shelf verification snippet for
either of those is usually a copy-paste away from working here too.
const crypto = require("crypto");
function verifyBytemonkWebhook(rawBody, signatureHeader, secret) {
const [tPart, v1Part] = signatureHeader.split(",");
const timestamp = tPart.replace("t=", "");
const providedSignature = v1Part.replace("v1=", "");
const expectedSignature = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
if (expectedSignature !== providedSignature) {
throw new Error("Signature mismatch — reject this request");
}
// Optional but recommended: reject deliveries older than a few minutes to limit the window a captured
// request could be replayed in.
const ageSeconds = Math.floor(Date.now() / 1000) - Number(timestamp);
if (ageSeconds > 300) {
throw new Error("Signature timestamp too old — possible replay");
}
}
Compute the HMAC over the exact bytes Bytemonk sent, before any JSON parsing — re-serializing a parsed object
(different key order, whitespace, etc.) produces a different string and a signature mismatch that has nothing to
do with an actual security problem. Most web frameworks expose a way to access the raw body for this exact reason
(e.g. Express's express.raw() instead of express.json() on this specific route).
Retry behavior
A delivery that doesn't get a 2xx response (or times out) is retried several times with increasing delays
between attempts, up to a bounded number of total attempts — after which it's given up on and not retried again.
Design your endpoint accordingly:
- Respond quickly — ideally under a second — and return a
2xxstatus as soon as you've durably queued the event for your own processing. Don't do slow work (calling other services, heavy DB writes) inline in the request handler before responding; a delivery that times out on your end looks identical to one that failed on ours, and gets retried the same way. - Handle duplicate deliveries — a retry after a timeout can occur even if your endpoint actually processed the
original attempt (the timeout was on the response, not the processing). Use
X-Bytemonk-Webhook-Deliveryto de-duplicate if your own processing isn't naturally idempotent.
If you suspect deliveries aren't arriving, contact your Bytemonk account contact to check delivery status on the admin side rather than trying to infer it from your own endpoint's logs alone.