Referência da API

Eventos de webhook

O catálogo de eventos que a WASViking emite, o formato do payload e como verificar a assinatura.

A WASViking^® emite eventos de webhook assinados a cada transição de estado relevante. Os eventos são JSON sobre HTTPS para uma URL que você registra, com assinatura HMAC-SHA256.

Registrando um webhook

curl -sS https://api.wasviking.com/v1/webhooks \
  -H "Authorization: ApiKey ${KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/wasviking-hook",
    "events": ["finding.escalated", "finding.sla_breached"],
    "description": "SIEM ingestion"
  }'

{
  "id": "wh_88aa12",
  "url": "https://example.com/wasviking-hook",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
  "events": ["finding.escalated", "finding.sla_breached"]
}

O secret é exibido uma única vez, na criação. Guarde-o; não é possível recuperá-lo depois.

Catálogo de eventos

Achados

Evento	Quando
`finding.created`	Um novo achado é gravado.
`finding.reopened`	Um achado que estava fechado voltou.
`finding.escalated`	O status ou a pontuação de risco saltou para uma faixa mais alta.
`finding.status_changed`	Qualquer transição de status.
`finding.sla_breached`	O achado ultrapassou a sua janela de SLA.
`finding.assigned`	Campo de responsável atualizado.

Scans

Evento	Quando
`scan.queued`	Scan aceito na fila.
`scan.started`	O scan passou para o estado de execução.
`scan.completed`	Scan concluído (com ou sem achados).
`scan.failed`	Erro do motor ou timeout rígido.
`scan.canceled`	Cancelamento pelo operador.

Inventário e ativos

Evento	Quando
`asset.first_seen`	Novo ativo descoberto.
`asset.disappeared`	O ativo não está mais acessível.
`asset.reappeared`	O ativo retornou após um `disappeared`.

Cadeia de suprimentos

Evento	Quando
`sbom.submitted`	Um novo SBOM chegou via `/sentinel/sbom/submit`.
`sbom.intel_match`	A ingestão diária de OSV+KEV casou com um SBOM ativo.
`bundle.created`	SBOM Evidence Bundle emitido.
`bundle.accessed`	O destinatário acessou um compartilhamento.
`bundle.revoked`	O operador revogou um compartilhamento.

Secrets

Evento	Quando
`secret.detected`	Uma nova detecção de secret chegou.
`secret.verified_live`	O verificador ao vivo confirmou que o secret está ativo.

Inteligência de edge

Evento	Quando
`edge.correlation_match`	Tráfego adversário correspondeu a um achado aberto (amplificação de risco).

Formato do payload

Todo evento é um objeto JSON com:

{
  "id": "evt_88aa12d4",
  "type": "finding.escalated",
  "created_at": "2026-05-21T14:08:11Z",
  "organization": "acme",
  "data": {
    "finding_id": "f_8ab2",
    "category": "graphql_bola",
    "cwe": "CWE-639",
    "risk_score": 88,
    "previous_risk_score": 62,
    "asset_id": "a_19ff",
    "asset_criticality": "high",
    "sla_window_hours": 24,
    "primary_risk_category": "authorization",
    "compliance": ["PCI 6.5.8", "LGPD Art.46"]
  }
}

O type diz ao seu consumidor como ler data. Trate tipos de evento desconhecidos como compatíveis com versões futuras: registre em log e ignore, em vez de falhar.

Assinatura

A WASViking assina todo payload com HMAC-SHA256 usando o secret do seu webhook.

Headers em toda entrega:

Header	Valor
`Wasviking-Signature`	`t=<timestamp>,v1=<hex-hmac>`
`Wasviking-Event`	O tipo do evento, espelhado no corpo.
`Wasviking-Delivery`	UUID desta tentativa de entrega.

Verificando em Python

import hmac, hashlib, time

def verify(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp = int(parts["t"])
    sig = parts["v1"]
    if abs(time.time() - timestamp) > tolerance:
        return False
    payload = f"{timestamp}.".encode() + body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Verificando em Node

const crypto = require("crypto");

function verify(body, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const payload = `${parts.t}.${body}`;
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Semântica de entrega

Pelo menos uma vez (at-least-once). Um erro de rede gera novas tentativas com backoff exponencial por até 24 horas.
Ordenada por achado. Os eventos do mesmo achado são entregues em ordem.
Entrega de teste. POST /webhooks/{id}/test envia um payload sintético webhook.test para verificar o seu endpoint.

Padrões comuns de consumo

SIEM. Assine finding.*, secret.verified_live e sbom.intel_match. Encaminhe direto para o índice do seu SIEM.
Slack / Teams. Assine finding.escalated e finding.sla_breached. A maioria das equipes considera assinaturas mais amplas ruidosas.
Automação interna. Assine asset.first_seen para disparar fluxos de trabalho internos de ativos.