FixWeb

// docs / webhooks

Webhooks

FixWeb 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 FixWeb 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 terminal. Payload: id del escaneo, fase fallida, error y enlace al reporte.
  • 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://fixweb.app/dashboard/scans/8f1c4e2a-..."
    }
  }
}

Firma

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

  • fixweb-signature: t=<timestamp>,v1=<hex hmac>
  • fixweb-event: scan.completed
  • fixweb-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, timeout, fallo DNS o bloqueo de seguridad SSRF se reintenta con backoff exponencial durante unas 24 horas. Las filas de entrega muestran estado de respuesta, un extracto corto, número de intentos y estado dead-letter en Cuenta → Webhooks.

Webhooks — Docs · FixWeb