Skip to main content
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

Forma do envelope

Cada delivery POST chega no endpoint registrado com este corpo:
E estes headers:

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>").
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. 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

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