FixVibe

// docs / webhooks

Webhooks

FixVibe sendet signierte ausgehende Webhooks für abgeschlossene Scans, terminale Fehler, Findings mit hoher Schwere, Live-Monitor-Alarme und geplante Läufe. Zustellungen sind at-least-once und werden etwa 24 Stunden lang wiederholt.

Einrichtung

Öffne Konto → Webhooks, erstelle einen HTTPS-Endpoint und speichere das einmalig angezeigte whsec_-Secret in deinem Empfänger. Webhooks gibt es in bezahlten Plänen.

  1. Erstelle einen Endpoint unter Konto → Webhooks.
  2. Wähle, welche Events FixVibe an diesen Endpoint senden soll.
  3. Kopiere das Secret sofort; es wird nur einmal angezeigt und kann später nur rotiert werden.

Events

Die Launch-Eventfläche deckt die Momente ab, die Teams typischerweise an CI, Alerting oder Tickets anbinden:

  • scan.completed — feuert, wenn ein Scan zu completed wechselt. Payload: Scan-ID, Ziel, Modus, Schweregrad-Zähler, Link zum Bericht.
  • scan.failed — terminal-failure notification. Payload: scan id, failure reason, and report link when available.
  • finding.created — wird pro critical- oder high-Finding ausgelöst. Niedrigere Schweregrade bleiben standardmäßig in scan.completed, um Event-Spam zu vermeiden.
  • monitor.alert.fired — feuert im Unlimited-Plan, wenn Certificate-Transparency-Logs, DNS-Einträge oder Threat-Intelligence-Datenbanken Änderungen erkennen.
  • schedule.run.queued — feuert, wenn der Scheduler einen Re-Scan einreiht. Nützlich für CI-Orchestrierung.

Payload-Form

Jede Zustellung nutzt denselben Umschlag: <code>id</code>, <code>type</code>, <code>created_at</code> und event-spezifisches <code>data</code>.

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-..."
    }
  }
}

Signierung

FixVibe signiert den exakten rohen JSON-Body mit HMAC-SHA-256. Prüfe die Signatur, bevor du Eventdaten parst oder ihnen vertraust. Header:

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

Wiederholungen

Any non-2xx response, timeout, DNS failure, or delivery safety rejection is retried with exponential backoff for about 24 hours. Delivery rows show response status, a short response excerpt, attempt count, and dead-letter state in Account → Webhooks.

Webhooks — Docs · FixVibe