Webhooks

Como funciona

• Depois de cada verificação, cada evento de incidente que passa pelas regras da organização (eventos, gravidade mínima e exceções) e pelo filtro do próprio webhook (gravidade mínima e eventos) é enviado ao webhook.
• Os eventos são opened (Nova queda), escalated (Queda piorou) e resolved (Normalizou). Uma piora vinda de abaixo da gravidade mínima do webhook chega como opened, porque é a primeira vez que o webhook fica sabendo do incidente.
• Cada evento é uma requisição, e as requisições para um mesmo webhook saem em ordem. Os webhooks nunca esperam o resumo diário.
• Os eventos por hora vêm da verificação regular de cada hora. Uma verificação pedida com Verificar agora pode enviar eventos das regras diárias.

Passo a passo

Requisição

POST /seu/caminho HTTP/1.1
Content-Type: application/json
User-Agent: Stealth-Webhooks/1
Stealth-Signature: t=1791554400,v1=<64 caracteres hexadecimais>

Corpo (versão v1)

{
  "version": "v1",
  "id": "evt_4f1c2b7e9a0d4e6b8c3a5f7d9e1b2c4a",
  "test": false,
  "event": "opened",
  "severity": "critical",
  "kind": "unit_silent",
  "occurred_at": "2026-10-09T14:00:00Z",
  "organization": {
    "id": "org_882ae4d9",
    "name": "Acme Media"
  },
  "network": {
    "code": "12345678",
    "name": "Acme Network"
  },
  "client": {
    "code": "987654",
    "name": "Example News"
  },
  "ad_unit": {
    "id": "23145678901",
    "name": "EXAMPLE_TOP",
    "format": "top"
  },
  "incident": {
    "id": "7d3f9a52-1c4e-4b8a-9f61-2e5d8c0b4a17",
    "started_at": "2026-10-09T13:00:00Z",
    "url": "https://app.usestealth.dev/console/incidents/7d3f9a52-1c4e-4b8a-9f61-2e5d8c0b4a17"
  },
  "estimated_loss": {
    "per_hour": 35.2,
    "currency": "BRL"
  }
}

Conferir a assinatura

1. Leia o corpo bruto antes de interpretar o JSON.
2. Calcule o HMAC e compare em tempo constante.
3. Recuse um t com mais de 5 minutos de diferença do seu relógio, para bloquear repetições.

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyStealthSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest()
  const given = Buffer.from(parts.v1 ?? '', 'hex')
  return given.length === expected.length && timingSafeEqual(given, expected)
}

import hashlib, hmac, time

def verify_stealth_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Respostas, tentativas e pausa

• Responda com qualquer 2xx em até 5 segundos. Se o seu processamento demora mais, responda primeiro e processe depois.
• A Stealth tenta até 3 vezes, esperando 1 segundo e depois 3 segundos, após um timeout, um erro de rede, 408, 429 ou um 5xx. Qualquer outra resposta falha na hora. Redirecionamentos nunca são seguidos, e o corpo da resposta nunca é lido.
• Quando um envio falha em todas as tentativas, os outros eventos daquela verificação não são enviados a esse webhook e aparecem como Não enviado no histórico. Eventos que falharam não são reenviados depois.
• Cada webhook tem até 60 segundos de cada verificação. Quando esse tempo acaba, os envios que ainda esperavam aparecem como Não enviado, com uma nota de que o tempo acabou. Eles não contam como falha e não são reenviados.
• Um webhook é pausado quando está falhando há 24 horas e pelo menos 3 verificações falharam nesse período. Todos os membros da organização recebem um aviso no app e por e-mail, e Proprietários e Administradores recebem o link para retomar. Um envio que funciona, ou um Enviar teste que recebe 2xx, zera a contagem. Os eventos que acontecem enquanto ele está pausado não são guardados. Escolha Retomar quando o endpoint voltar a funcionar.

O que você vê na tela

Como a Stealth protege as requisições que envia

• Só https, só a porta 443, e o certificado precisa ser válido.
• Nada de endereços IP nem de nomes privados ou internos.
• Redirecionamentos nunca são seguidos, e o corpo da resposta nunca é lido.
• O endereço é conferido quando você salva e de novo antes de cada envio.

Perguntas frequentes