Oferta para novos clientes−20 %20 % de desconto nos primeiros 3 meses com pagamento mensalVer planos
SilentShield

Os webhooks não chegam

Criou uma regra de alerta com o canal Webhook, mas o seu servidor não recebe nada. Veja aqui quando o SilentShield envia um webhook e o que o pode travar pelo caminho.

Quando o SilentShield envia um webhook

Só enviam webhooks as regras de alerta de uma chave API cujo canal é Webhook. Uma vez por minuto, o SilentShield verifica cada regra ativa. Se a condição for cumprida dentro da janela de tempo, envia um pedido POST para o URL do webhook guardado na página «Definições de notificação».

Causas

A regra nunca foi acionada

Na página «Regras de Alerta» da chave, a coluna «Última ativação» mostra quando uma regra foi acionada pela última vez. Se indicar «nunca», a condição ainda não foi cumprida e nada foi enviado. Compare o limiar e o operador com os números da sua análise.

A regra aguarda o fim da sua janela de tempo

Uma regra é acionada no máximo uma vez por janela de tempo (5m, 15m, 1h, 24h). Depois disso, só volta a ser verificada quando a janela terminar: uma regra com 24h envia no máximo uma vez por dia.

Não há nenhum URL de webhook guardado

A regra apenas escolhe o canal; o endereço em si é guardado na página «Definições de notificação». Sem endereço, a regra é acionada, mas nada é enviado. Só pode guardar um endereço com um plano que inclua integrações de webhook.

O endereço não é acessível a partir da internet

O SilentShield só entrega a endereços públicos. Destinos locais e internos como localhost, 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16 ou 172.16.0.0/12 são recusados ao guardar e novamente ao ligar, também depois de um redirecionamento. Para testes locais, use um túnel com um endereço HTTPS público.

O seu servidor responde demasiado devagar

Cada tentativa espera no máximo 5 segundos pela resposta completa. Responda de imediato com um estado 2xx e processe a mensagem depois, por exemplo numa fila.

O seu servidor responde com um erro ou um redirecionamento

Só os códigos de estado de 200 a 299 contam como entregues. Após um 5xx, 408 ou 429, ou se a ligação falhar, o SilentShield tenta de novo após 2 e após 8 segundos e depois desiste. Outros códigos 4xx, como 401, 403 ou 404, não são repetidos; uma firewall ou uma proteção contra bots à frente do seu endpoint responde muitas vezes com 403. Após um redirecionamento 301, 302 ou 303, o pedido continua como GET sem corpo, por isso indique o endereço final.

A verificação da assinatura falha no seu servidor

Se guardou um segredo, cada pedido traz o cabeçalho X-Signature-256: sha256= seguido do HMAC-SHA256 do corpo em hexadecimal. Calcule-o sobre o corpo em bruto exatamente como chega, antes de analisar o JSON; um corpo analisado e novamente serializado tem outra assinatura. Sem segredo, o cabeçalho não existe.

O que chega ao seu servidor

Uma entrega tem este aspeto. O X-Event-ID mantém-se igual em todas as tentativas de uma entrega; use-o para reconhecer duplicados.

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-Event-ID: 8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d
X-Signature-256: sha256=<hex>

{
  "event_id": "8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d",
  "alert_rule_id": "2a7c9e1b-3d4f-4b6a-8c0e-1f2a3b4c5d6e",
  "alert_name": "bot-rate",
  "api_key_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "metric": "bot_rate",
  "operator": "gt",
  "threshold": 0.3,
  "value": 0.42,
  "fired_at": "2026-11-16T10:30:00Z"
}

Verificar a assinatura

Exemplo em Node.js; rawBody é o corpo do pedido sem alterações:

const crypto = require("crypto");

function isValidSignature(rawBody, header, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = header || "";
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

// header = req.get("X-Signature-256")

Como configurar regras e canais: Regras de Alerta