/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
Forma do envelope
Cada delivery POST chega no endpoint registrado com este corpo:Verificação de assinatura (HMAC-SHA256)
O headerX-ConsentFly-Signature segue o mesmo formato do Stripe: t=<timestamp>,v1=<hex>. O valor v1 é HMAC_SHA256(secret, "<t>.<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.
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, oiddo 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
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
