Webhooks - ConsentFly

Webhooks são a forma do ConsentFly empurrar eventos para o seu backend em tempo real, em vez de você ter que ficar fazendo polling em /api/v1/consents. Ideal para integrar com CDPs, ferramentas de analytics, pipelines de opt-out e qualquer sistema que precise reagir imediatamente quando um titular muda de ideia.

Gerenciamento é via dashboard. Endpoints, secrets e tentativas de reentrega são geridos em https://www.consentfly.com.br/dashboard/webhooks. Esta página documenta apenas o lado consumidor — o que seu servidor recebe e como validar a assinatura.

Catálogo de eventos

Tipo	Quando dispara	Payload (`data`)
`consent.created`	Banner público registra um consentimento OU `POST /consents` é chamado	`ConsentDTO`
`consent.updated`	`PUT /consents/{id}` mantém o status aceito	`ConsentDTO`
`consent.revoked`	`PUT /consents/{id}` muda `accepted` de `true` para `false`, ou `DELETE /consents/{id}`	`ConsentDTO`
`consent.erased`	`DELETE /consents/by-subject/{subjectId}` (DSAR)	`{subject_id, site_id, erased}` agregado
`policy.published`	Política criada OU atualizada (cada `version` é um publish)	`PolicyResponse`

Forma do envelope

Cada delivery POST chega no endpoint registrado com este corpo:

{
  "id": "evt_<32hex>",
  "type": "consent.created",
  "created_at": "2026-05-15T12:34:56Z",
  "data": { "...": "DTO conforme tabela acima" }
}

E estes headers:

Content-Type:           application/json
User-Agent:             ConsentFly-Webhooks/1.0
X-ConsentFly-Event:     consent.created
X-ConsentFly-Delivery:  <uuid do delivery>
X-ConsentFly-Signature: t=<unix>,v1=<hex_hmac>

Verificação de assinatura (HMAC-SHA256)

O header X-ConsentFly-Signature segue o mesmo formato do Stripe: t=<timestamp>,v1=<hex>. O valor v1 é HMAC_SHA256(secret, "<t>.<corpo_bruto>").

import crypto from "node:crypto";

function verify(req, rawBody, secret) {
  const header = req.headers["x-consentfly-signature"];
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  if (!parts.t || !parts.v1) return false;

  // Rejeite deliveries com mais de ~5 min de skew para mitigar replay.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(parts.t)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(parts.v1, "hex")
  );
}

Importante: use o corpo bruto (raw) — não o JSON re-serializado pelo seu framework. Re-encoding muda whitespace e quebra a assinatura.

Política de retry e auto-disable

Timeout por entrega: o dispatcher espera no máximo 10 segundos pela resposta do seu endpoint (incluindo TLS handshake). Qualquer status HTTP 2xx dentro desse limite conta como entrega bem-sucedida; qualquer outra coisa (status não-2xx, timeout, falha de conexão) entra na fila de retry.

Tentativa	Espera até a próxima
1 → 2	30s
2 → 3	2min
3 → 4	10min
4 → 5	1h
5 → `exhausted`	6h (último hold, depois para)

Máximo de 5 tentativas. Após a 5ª falha o delivery vira exhausted e só volta a executar via replay no dashboard. No nível do endpoint, 50 falhas consecutivas disparam auto-disable: o ConsentFly desliga o endpoint, marca auto_disabled_at e mostra um pill “Desabilitado automaticamente” no dashboard. Para religar, edite o endpoint pelo painel (isso zera o contador).

Boas práticas

Responda 2xx rápido (< 10s). O dispatcher tem timeout de 10 segundos por delivery, incluindo TLS handshake. Se o seu processamento for pesado, enfileire localmente e responda 200 imediato.
Idempotência via X-ConsentFly-Delivery. Em caso de retry, o id do delivery se repete — use-o como chave de idempotência no seu lado.
Aceite somente HTTPS. O ConsentFly bloqueia URLs http:// em produção e refuse redirecionamentos 30x — então não tente “redirecionar internamente” o webhook.
Não bloqueie IPs. As entregas saem da infra do ConsentFly (Cloudflare → Railway) e os ranges podem mudar. Se você precisa de allowlist, use a assinatura HMAC como confirmação criptográfica em vez de filtro de IP.

Caps por plano

Plano	Endpoints máximos
Free / Starter	10
Pro / Enterprise	50

A gestão dos endpoints (criar, editar, desabilitar, reenviar deliveries falhadas) acontece só pelo dashboard — não há endpoints API-key para isso por enquanto. Se o seu fluxo precisa criar webhooks programaticamente, fale com a gente.

Dúvidas? suporte@consentfly.com.br

Documentation Index

​Catálogo de eventos

​Forma do envelope

​Verificação de assinatura (HMAC-SHA256)

​Política de retry e auto-disable

​Boas práticas

​Caps por plano