Skip to main content

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.

Setting up a webhook

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 typeFired whendata fields
notice.publishedA DRAFT notice is published (becomes the ACTIVE version)noticeId, noticeGroupKey, language, version
consent.grantedA 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.withdrawnA principal withdraws consent (whole-notice or single-purpose), or a consent record is automatically withdrawn once every granted purpose has exceeded its own retentionPeriodDaysconsentRecordId, 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.expiredA 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 withdrawalconsentRecordId, principalId, noticeId, purposeCode (always null — the whole record expired), retentionPeriodDays
consent.renewal_requiredA 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 principalnoticeId, noticeGroupKey, language, version, purposeCodes (the purposes now flagged requiresReconsent), staleConsentCount (how many existing consent records under the previous version are now outdated)
preference.changedA grant includes topic or preference answers (see choices). Fired alongside consent.grantedconsentRecordId, principalId, noticeId, choices
consent.unsubscribed_allA principal withdrew everything they can withdraw in one step (see Unsubscribe from everything)principalId, noticesWithdrawn, reason (null when none given)
profile.updatedA principal's profile answers changed. Carries field codes only, never the answersprincipalId, fields (the codes that changed)
consent.snooze_endedA purpose a principal withdrew "for now" (see snooze) is undecided again because its date passedconsentRecordId, principalId, noticeId, purposeCode, snoozedUntil
collection_point.submittedA visitor submitted a collection point's web formcollectionPointCode, version, principalId, consentRecordId (never the answers)
preference_center.publishedA preference center design is published from the dashboardcode, version
privacy_policy.version_changedAn 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 typeFired whendata fields
dsr.submittedA principal submits a DSR request (see Submit a DSR Request)dsrRequestId, referenceId, principalId, requestType
dsr.acknowledgedAn admin acknowledges a submitted DSR requestdsrRequestId, referenceId, principalId
dsr.fulfilledA DSR request is fulfilled — access, correction, or erasuredsrRequestId, referenceId, principalId, requestType
dsr.rejectedA DSR request is rejecteddsrRequestId, referenceId, principalId, reason
dsr.communication_addedA 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 typeFired whendata fields
grievance.filedA principal files a grievance (see File a Grievance)grievanceId, referenceId, principalId, category
grievance.acknowledgedAn admin acknowledges a filed grievancegrievanceId, referenceId, principalId
grievance.resolvedA grievance is resolvedgrievanceId, referenceId, principalId, resolutionNotes
grievance.escalatedA grievance is escalated to the Data Protection Board (DPB)grievanceId, referenceId, principalId
grievance.assignedA grievance is assigned to (or unassigned from) a grievance officergrievanceId, referenceId, officerUserId (null when unassigned)
grievance.communication_addedA message is added to a grievance's communication thread — by the principal, a DPO/officer, or automatically by Bytemonk itselfrequestId, 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:

HeaderMeaning
X-Bytemonk-Webhook-Signaturet=<unix-timestamp>,v1=<hex-hmac> — see below
X-Bytemonk-Webhook-EventSame value as the body's eventType, for routing without parsing JSON first
X-Bytemonk-Webhook-DeliveryAn 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");
}
}
Use the raw request body, not a re-serialized copy

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 2xx status 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-Delivery to 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.