Consent & DSAR webhook

Embed
Preview of the card
<a href="https://forumulate.com/guides/cookies-consent-webhook"><img src="https://forumulate.com/guides/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/36aa4df0-1e95-4cef-8ae9-795169441345/pages/8e500e1b-7258-4bb0-9e79-f8dd0ee030ca/social-card.svg?v=3e7ae33eec8b" alt="Consent &amp; DSAR webhook" width="600" height="315"></a>

Most CMPs can call a webhook when something changes — a consent record updates, or a reader files a data-subject request (DSAR: "export my data" / "delete my account"). Forumulate gives every organization its own signed webhook endpoint so any CMP can deliver those events, and a data-subject deletion or access request flows straight through to erase or export the underlying account.

This endpoint is provider-agnostic — it works for CookieMunch, or any other CMP that signs its webhooks with an HMAC.

Your endpoint

POST https://<your-site>/api/hooks/consent/<your-org-id>

The exact URL for your organization is returned by GET /orgs/:orgId/consent as webhookUrl — copy it into your CMP's webhook subscription.

The signing secret

Authenticity is proven by an HMAC-SHA256 signature over the raw request body, keyed with a secret only you and your CMP know. There are two ways to establish it:

  1. Use the secret your CMP issued. When your vendor generated the webhook subscription it gave you a signing secret (CookieMunch calls it whsec_…). Store it on Forumulate by setting webhookSecret on your consent config:

    PUT /orgs/:orgId/consent
{ "provider": "cookiemunch", "preset": { "cbid": "…" }, "webhookSecret": "whsec_xxx" }

  2. Let us generate one. Call rotate to mint a fresh secret, then paste it into your CMP:

    POST /orgs/:orgId/consent/webhook-secret
→ 201 { "secret": "whsec_…", "webhookUrl": "https://…/api/hooks/consent/…" }

webhookSecret is write-only. It is never returned by GET, never included in the public consent resolve, and the rotate call is the only time a generated secret is shown — copy it then. A read only ever tells you whether a secret is set, via webhookConfigured: true, plus the webhookUrl. Rotating immediately invalidates the previous secret.

Re-saving your consent config without webhookSecret preserves the stored one — you never have to resend it just to change your provider or preset.

How your CMP must sign

For each delivery, compute HMAC-SHA256(rawBody, secret) and send it in a signature header. Forumulate accepts, in order:

  • X-Consent-Signature (generic, recommended)

  • X-CookieMunch-Signature / CookieMunch-Signature

  • X-Webhook-Signature

The value may be the hex or base64 digest, optionally prefixed sha256=. If your CMP also sends a timestamp header (X-Consent-Timestamp or X-CookieMunch-Timestamp), the signed content may be {timestamp}.{body} — both forms are checked. Verification is timing-safe.

A delivery with a missing or bad signature is rejected with 401; an org with no secret configured returns 404 (the endpoint is dark until you wire it).

What happens on a DSAR

When a verified dsar.created event arrives, Forumulate:

  1. Looks up the local account by the subject's email.

  2. Asks the identity platform to erase (for a deletion request) or export (for an access request) that account.

  3. Advances the request to completed only if that succeeded — a failure leaves the request open for retry, never falsely closed.

Other event types are acknowledged and ignored, so subscribing to your CMP's full event stream is safe.

See the Consent API reference for the full request/response shapes.

The Forumulate teamUpdated