FixVibe

// docs / webhooks

Webhooks

FixVibe envía webhooks salientes firmados para escaneos completados, fallos terminales, hallazgos de alta severidad, alertas de monitoreo en vivo y ejecuciones programadas. Las entregas son al menos una vez y se reintentan durante unas 24 horas.

Configuración

Abre Cuenta → Webhooks, crea un endpoint HTTPS y guarda el secreto de un solo uso whsec_ en tu receptor. Los webhooks están disponibles en planes de pago.

  1. Crea un endpoint desde Cuenta → Webhooks.
  2. Elige qué eventos debe enviar FixVibe a ese endpoint.
  3. Copia el secreto de inmediato; se muestra una sola vez y después solo se puede rotar.

Eventos

La superficie de eventos de lanzamiento cubre los momentos que los equipos suelen conectar a CI, alertas o tickets:

  • scan.completed — se dispara cuando un escaneo pasa a completed. Payload: id del escaneo, objetivo, modo, conteos por severidad y enlace al reporte.
  • scan.failed — notificación de fallo del terminal. Carga útil: identificación del escaneo, motivo del error y enlace del informe cuando esté disponible.
  • finding.created — se emite por cada hallazgo critical o high. Las severidades menores se agrupan en scan.completed por defecto para evitar ruido.
  • monitor.alert.fired — se dispara en el plan Unlimited cuando los logs de certificate transparency, DNS o bases de threat intelligence detectan cambios.
  • schedule.run.queued — se dispara cuando el programador pone en cola un reescaneo. Útil para orquestación de CI.

Forma del payload

Cada entrega usa el mismo sobre: <code>id</code>, <code>type</code>, <code>created_at</code> y <code>data</code> específico del 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-..."
    }
  }
}

Firma

FixVibe firma el cuerpo JSON exacto con HMAC-SHA-256. Verifica la firma antes de parsear o confiar en los datos del evento. Headers:

  • fixvibe-signature: t=<timestamp>,v1=<hex hmac>
  • fixvibe-event: scan.completed
  • fixvibe-delivery: <uuid> (clave de idempotencia)
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);
}

Reintentos

Cualquier respuesta que no sea 2xx, tiempo de espera, falla DNS o rechazo de seguridad de entrega se reintenta con un retraso exponencial durante aproximadamente 24 horas. Las filas de entrega muestran el estado de la respuesta, un breve extracto de la respuesta, el recuento de intentos y el estado de los mensajes fallidos en Cuenta → Webhooks.

Webhooks — Docs · FixVibe