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 – Benachrichtigung über Terminalfehler. Nutzlast: Scan-ID, Fehlergrund und Berichtslink, sofern verfügbar.
  • 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

Jede Nicht-2xx-Antwort, Zeitüberschreitung, DNS-Fehler oder Ablehnung der Zustellungssicherheit wird mit exponentiellem Backoff für etwa 24 Stunden wiederholt. Zustellungszeilen zeigen den Antwortstatus, einen kurzen Antwortauszug, die Anzahl der Versuche und den Status unzustellbarer Nachrichten unter Konto → Webhooks.