Endpoints de Webhook
Cada organização pode configurar múltiplos endpoints para receber notificações de eventos.
Campos do Endpoint
| Campo | Descrição |
|---|---|
| URL | Endereço HTTPS que receberá as notificações |
| Descrição | Descrição do endpoint (máx 255 caracteres) |
| Eventos | Lista de tipos de eventos inscritos |
| Segredo | Chave HMAC-SHA256 para validação de assinatura |
| Ativo | Se o endpoint está habilitado |
Criando um Endpoint
Ao criar, o sistema gera automaticamente um segredo (whsec_...) que é mostrado apenas na criação. Armazene-o com segurança — ele é necessário para validar as assinaturas dos webhooks.
Assinatura dos Webhooks
Cada entrega inclui um header de assinatura:
X-Webhook-Signature: t=<timestamp>,v1=<sha256_hex>
Verificação
- Extraia o timestamp e a assinatura do header
- Reconstrua:
${timestamp}.${payload_json} - Compute HMAC-SHA256 usando o segredo
- Compare com a assinatura (comparação timing-safe)
Rotação de Segredo
Quando suspeitar que o segredo foi comprometido, use a rotação de segredo. Um novo segredo é gerado e o anterior é invalidado imediatamente.
Teste de Webhook
Envie um payload de teste para verificar se o endpoint está configurado corretamente. O resultado inclui o status HTTP e a resposta recebida.
Desativação Automática
Após 10 falhas consecutivas de entrega, o endpoint é desativado automaticamente. Para reativar, corrija o problema e atualize o endpoint para ativo.
Proteção contra SSRF
URLs são validadas para rejeitar IPs privados e localhost, prevenindo ataques de Server-Side Request Forgery.