Formato do webhook

O SilentShield pode enviar notificações em tempo real para o seu servidor através de webhooks. Configure os URLs de webhook em Painel → Notificações.

Estrutura do payload

Todos os payloads de webhook seguem esta estrutura:

{"event": "bot_detected", "timestamp": "2025-01-15T10:30:00Z", "data": {"keyId": "key_abc", "domain": "example.com", "ip": "203.0.113.42", "verdict": "bot", "score": 0.15, "userAgent": "Mozilla/5.0...", "page": "/contact"}}

Tipos de evento

Event	Description
`bot_detected`	Acionado quando um pedido é classificado como bot.
`bot_spike`	Acionado quando as deteções de bots ultrapassam o limiar de alerta na janela configurada.
`quota_warning`	Acionado quando a utilização da quota atinge 80% ou 90%.
`quota_exceeded`	Acionado quando a quota mensal é ultrapassada.
`domain_verification_failed`	Acionado quando uma nova verificação de domínio falha.
`key_rotated`	Acionado quando uma API key é rodada.

Verificação da assinatura

Cada webhook inclui um cabeçalho X-SilentShield-Signature que contém uma assinatura HMAC-SHA256. Verifique esta assinatura para garantir que o webhook é autêntico.

Obtenha o corpo bruto do pedido (como string, antes da análise)
Obtenha o valor do cabeçalho X-SilentShield-Signature
Calcule o HMAC-SHA256 do corpo com o seu segredo de webhook como chave
Compare a assinatura calculada com o valor do cabeçalho

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Política de tentativas

Se o seu endpoint devolver um código de estado não-2xx ou exceder o tempo limite (10 segundos), o SilentShield tenta novamente a entrega até 3 vezes com backoff exponencial (1 minuto, 5 minutos, 30 minutos). Após 3 tentativas falhadas, o webhook é marcado como falhado e fica visível em Painel → Notificações → Entregas falhadas.

Segredo do webhook

O segredo do webhook é gerado quando cria um endpoint de webhook no painel. Pode visualizá-lo ou regenerá-lo em Painel → Notificações → Webhooks → Editar.