Webhooks

Configure e receba eventos do AdFlow via webhooks.

Receba notificações em tempo real no seu servidor quando algo acontece no AdFlow.

Como funciona

1. Você cadastra uma URL HTTPS + segredo em /webhook_endpoints/new
2. Seleciona quais eventos quer receber
3. Quando o evento ocorre, o AdFlow faz POST para sua URL com payload JSON
4. Seu servidor valida a assinatura e processa o payload

Configurar endpoint

Em /webhook_endpoints/new:

• URL: deve ser HTTPS e acessível publicamente. Sem suporte a localhost em produção.
• Segredo: string aleatória (mínimo 32 caracteres). Use openssl rand -hex 32 para gerar.
• Eventos: selecione os tipos que quer receber. Recomendado começar com campaign.* e webhook.failed.

Após salvar, clique Enviar evento de teste para confirmar que sua URL está recebendo.

Eventos disponíveis

Formato do payload

{
  "id": "evt_abc123",
  "event": "campaign.enqueued",
  "occurred_at": "2026-05-03T10:00:00Z",
  "organization_id": "org_xyz789",
  "data": {
    "resource_type": "campaign",
    "resource_id": "cmp_def456",
    "changes": {}
  }
}

Validar assinatura HMAC

Todo POST inclui o header X-AdFlow-Signature: HMAC-SHA256 do body usando o seu segredo. Sempre valide antes de processar.

# Ruby
secret   = ENV['ADFLOW_WEBHOOK_SECRET']
expected = OpenSSL::HMAC.hexdigest('SHA256', secret, request.raw_post)
received = request.headers['X-AdFlow-Signature']
halt 401 unless ActiveSupport::SecurityUtils.secure_compare(received, expected)

# Python
import hmac, hashlib, os
secret   = os.environ['ADFLOW_WEBHOOK_SECRET'].encode()
expected = hmac.new(secret, request.body, hashlib.sha256).hexdigest()
received = request.headers.get('X-AdFlow-Signature', '')
if not hmac.compare_digest(expected, received):
    abort(401)

Retry policy

Se o seu servidor retornar erro (4xx, 5xx) ou não responder em 10s, o AdFlow tenta novamente:

Após 3 falhas consecutivas, registra webhook.failed no audit log e para de tentar para aquele evento.

Seu endpoint deve responder 200 OK mesmo que decida não processar o evento — assim o AdFlow não re-envia.