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 leva os headers padrão Kobana (X-Kobana-App, X-Kobana-Environment, X-Kobana-Webhook-Id, X-Kobana-Event, X-Kobana-Event-Id, X-Kobana-Delivery-Id, X-Kobana-Timestamp, X-Kobana-Signature) e o trio webhook-id / webhook-timestamp / webhook-signature no layout Standard Webhooks:

X-Kobana-Signature: v1,<base64(HMAC_SHA256(chave, delivery_id + "." + timestamp + "." + body_cru))>

Verificação

1. Leia webhook-id, webhook-timestamp e webhook-signature
2. Rejeite se o timestamp estiver a mais de 5 minutos do relógio atual
3. Reconstrua delivery_id.timestamp.body_cru e calcule o HMAC-SHA256 com a chave (base64 decodificado do secret sem o prefixo whsec_)
4. Compare com cada token v1, do header em tempo constante

O algoritmo completo, com exemplos em Node.js e Python, está em Referência da API — Webhooks. O header legado X-Signature (t=<unix>,v1=<hex>) continua sendo enviado, deprecado.

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.