Pular para o conteúdo principal

​
Como configurar

  1. Acesse a página de Integração no painel (ou use as rotas de Webhooks - Endpoints, com uma API Key de escopo WEBHOOKS)
  2. Crie um Endpoint de Webhook informando a URL pública do seu servidor e selecionando os eventos que deseja receber
  3. Copie a credencial exibida na criação (mostrada apenas uma vez) — ela é usada para validar a assinatura HMAC
  4. Seu servidor deve responder com um status 2xx (ex.: 200) para confirmar o recebimento. Redirecionamento (3xx) não é seguido e conta como falha: cadastre a URL final
  5. Em caso de falha, o sistema realiza novas tentativas de reenvio com backoff exponencial
Você pode cadastrar vários endpoints. Cada um recebe apenas os eventos que assina e possui sua própria credencial. Um mesmo evento é entregue a todos os endpoints que o assinam.

​
Eventos disponíveis

Ao criar ou atualizar um endpoint, assine pelo valor (coluna 1). O payload enviado identifica o evento pelo campo event (coluna 4) junto com o status; o nome legível (coluna 2) aparece só na lista de eventos e nas entregas.

​
Segurança — Assinatura HMAC

Toda requisição de webhook inclui o header Alpha-Signature para você verificar a autenticidade e a integridade do payload:
  • t — timestamp Unix (segundos) de quando a notificação foi assinada
  • v1 — HMAC-SHA256, em hexadecimal, da string {t}.{corpo_bruto_da_requisição} usando a credencial do endpoint como chave
Para validar: recalcule o HMAC-SHA256 de {t}.{corpo_bruto} com a credencial do endpoint e compare com v1 usando comparação de tempo constante. Rejeite se o timestamp t estiver fora de uma janela de tolerância (ex: 300 segundos).
Use o corpo bruto (raw) da requisição na verificação, não o JSON re-serializado.
Compatibilidade: integrações que usavam a configuração antiga (header X-Webhook-Secret) continuam funcionando — esse header ainda é enviado quando há uma credencial configurada. O Alpha-Signature é adicional e recomendado.