FixVibe

// docs / webhooks

Webhooks

FixVibe envia webhooks de saída assinados para conclusão de varredura, falhas de terminal, descobertas de alta gravidade, alertas de monitor ao vivo e execuções programadas. As entregas são feitas pelo menos uma vez e repetidas por cerca de 24 horas.

Setup

Abra Account → Webhooks, crie um endpoint HTTPS e armazene o segredo whsec_ único em seu receptor. Webhooks estão disponíveis em planos pagos.

  1. Crie um endpoint de Account → Webhooks.
  2. Escolha quais eventos FixVibe devem ser enviados para esse endpoint.
  3. Copie o segredo imediatamente; ele é mostrado uma vez e só pode ser girado posteriormente.

Events

A superfície do evento de lançamento cobre os momentos em que as equipes geralmente se conectam a CI, alertas ou emissão de tickets:

  • scan.completed — dispara quando uma varredura faz a transição para completed. Carga útil: ID de verificação, destino, modo, contagens de intervalo de gravidade, link para o relatório.
  • scan.failed — notificação de falha do terminal. Carga útil: ID da verificação, motivo da falha e link do relatório, quando disponível.
  • finding.created — emitido por descoberta crítica ou alta. Gravidades mais baixas são reduzidas para scan.completed por padrão para evitar spam de eventos.
  • monitor.alert.fired — é acionado no plano Unlimited quando logs de transparência de certificados, registros DNS ou bancos de dados de inteligência de ameaças detectam alterações.
  • schedule.run.queued — é acionado quando o agendador enfileira uma nova varredura. Útil para orquestração CI.

Formato da carga útil

Cada entrega usa o mesmo envelope: <code>id</code>, <code>type</code>, <code>created_at</code> e <code>data</code> específico do evento.

json
{
  "id": "8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d",
  "type": "scan.completed",
  "created_at": "2026-05-15T10:20:30.000Z",
  "data": {
    "scan": {
      "id": "8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d",
      "target_hostname": "staging.example.com",
      "mode": "passive",
      "status": "completed",
      "findings_count": { "critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4 },
      "report_url": "https://fixvibe.app/dashboard/scans/8f1c4e2a-..."
    }
  }
}

Signing

FixVibe assina o corpo JSON bruto exato com HMAC-SHA-256. Verifique a assinatura antes de analisar ou confiar nos dados do evento. Cabeçalhos:

  • fixvibe-signature: t=<timestamp>,v1=<hex hmac>
  • fixvibe-event: scan.completed
  • fixvibe-delivery: <uuid> (chave de idempotência)
ts
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const signed = `${parts.t}.${rawBody}`;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  const calculated = Buffer.from(expected, "hex");
  return received.length === calculated.length && timingSafeEqual(received, calculated);
}

Retries

Qualquer resposta diferente de 2xx, tempo limite, falha DNS ou rejeição de segurança de entrega é repetida com espera exponencial por cerca de 24 horas. As linhas de entrega mostram o status da resposta, um breve trecho da resposta, a contagem de tentativas e o estado da mensagem morta em Conta → Webhooks.

Webhooks — Docs · FixVibe