Formato do webhook

O SilentShield pode enviar notificacoes em tempo real para o seu servidor atraves de webhooks. Configure os URLs de webhook em Painel → Notificacoes.

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 e classificado como bot.
`bot_spike`	Acionado quando as detecoes de bots ultrapassam o limiar de alerta na janela configurada.
`quota_warning`	Acionado quando a utilizacao da quota atinge 80% ou 90%.
`quota_exceeded`	Acionado quando a quota mensal e ultrapassada.
`domain_verification_failed`	Acionado quando uma re-verificacao de dominio falha.
`key_rotated`	Acionado quando uma API key e rodada.

Verificacao da assinatura

Cada webhook inclui um cabecalho X-SilentShield-Signature contendo uma assinatura HMAC-SHA256. Verifique esta assinatura para garantir que o webhook e autentico.

Obtenha o corpo bruto do pedido (como string, antes da analise)
Obtenha o valor do cabecalho X-SilentShield-Signature
Calcule o HMAC-SHA256 do corpo usando o seu segredo de webhook como chave
Compare a assinatura calculada com o valor do cabecalho

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)
  );
}

Politica de tentativas

Se o seu endpoint devolver um codigo de estado nao-2xx ou expirar o tempo limite (10 segundos), o SilentShield tenta novamente a entrega ate 3 vezes com backoff exponencial (1 minuto, 5 minutos, 30 minutos). Apos 3 tentativas falhadas, o webhook e marcado como falhado e fica visivel em Painel → Notificacoes → Entregas falhadas.

Segredo do webhook

O segredo do webhook e gerado quando cria um endpoint de webhook no painel. Pode visualiza-lo ou regenera-lo em Painel → Notificacoes → Webhooks → Editar.