Webhooks

Webhooks deliver CookieBeam events to an HTTPS endpoint you control. Webhooks are a plan-gated feature, and endpoint management is currently restricted: endpoints are configured for your team by CookieBeam rather than self-served in the dashboard. Each endpoint subscribes to a set of event types and has a signing secret, which starts with whsec_.

There are no public REST endpoints for webhook management. The webhooks:read and webhooks:write API key scopes exist on keys but currently gate nothing.

Event types

Six event types are currently emitted:

• consent.given — a visitor recorded an explicit consent choice
• scan.completed — a cookie scan finished
• scan.policy_update_needed — scan results require a policy review
• dsar.request_submitted — a data subject access request was submitted
• banner.published — a banner configuration was published
• compliance.report_generated — a compliance report was generated

The endpoint configuration form may list additional event types that are registered but not yet emitted by any code path — subscribing to one of those is accepted but delivers nothing. Subscribe only to the six above.

Delivery format

Each delivery is an HTTP POST with a JSON envelope:

{
  "event": "consent.given",
  "data": {
    "consentLogId": "9b2f7c14-8b3a-4e21-9d5c-1a2b3c4d5e6f",
    "bannerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "consentGiven": { "necessary": true, "analytics": false },
    "pageUrl": "https://example.com/pricing",
    "timestamp": "2026-08-13T12:00:00.000Z"
  },
  "timestamp": "2026-08-13T12:00:01.000Z",
  "deliveryId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

The data payload is the example above for consent.given; other event types carry their own payloads. Request headers:

Verify the signature

Recompute the HMAC over the exact raw request body and compare it against the signature header using a constant-time comparison:

const crypto = require('node:crypto');

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(signatureHeader || '', 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use the raw body as received — parsing and re-serializing the JSON can change the bytes and produce a false mismatch. Reject deliveries whose signature does not verify.

Receiving requirements

Your endpoint must:

• Use HTTPS with a publicly resolvable host. Private, loopback, and reserved IP addresses are rejected when the endpoint is created and again at delivery time.
• Answer directly. Redirects are refused and count as failed deliveries.
• Respond within 10 seconds. The response body is recorded only up to 4,000 characters.
• Return a 2xx status to acknowledge a delivery. Any other outcome follows the retry policy below.

Retries and disabling

Deliveries are queued and sent by a background runner that processes pending deliveries every few minutes. A failed delivery is retried up to 5 attempts in total, with delays of 1 minute, 5 minutes, 30 minutes, and 2 hours between attempts.

Network errors, timeouts, HTTP 5xx, 408, and 429 responses are retried. Other 4xx responses are treated as permanent rejections and are not retried, because the endpoint rejected the request itself.

An endpoint that accumulates 10 consecutive delivery failures is disabled automatically, and the team owner is notified by email. Ask CookieBeam to re-enable the endpoint once it is healthy again.