FixVibe

// docs / webhooks

Webhook

FixVibe invia webhook in uscita firmati per il completamento della scansione, errori del terminale, risultati di elevata gravità, avvisi di monitoraggio in tempo reale ed esecuzioni pianificate. Le consegne vengono effettuate almeno una volta e riprovate per circa 24 ore.

Setup

Apri Account → Webhooks, crea un endpoint HTTPS e memorizza il segreto whsec_ una tantum nel ricevitore. I webhook sono disponibili sui piani a pagamento.

  1. Crea un endpoint da Account → Webhooks.
  2. Scegli quali eventi FixVibe devono inviare a quell'endpoint.
  3. Copia immediatamente il segreto; viene mostrato una volta e può essere ruotato solo successivamente.

Events

La superficie dell'evento di lancio copre i momenti in cui i team solitamente si collegano a CI, inviando avvisi o emettendo ticket:

  • scan.completed: si attiva quando una scansione passa a completed. Payload: ID scansione, destinazione, modalità, conteggi dei bucket di gravità, collegamento al report.
  • scan.failed: notifica di errore del terminale. Payload: ID scansione, motivo dell'errore e collegamento al report quando disponibile.
  • finding.created — emesso per risultato critico o elevato. Per impostazione predefinita, i livelli di gravità inferiori vengono compressi in scan.completed per evitare spam negli eventi.
  • monitor.alert.fired: si attiva sul piano Unlimited quando i registri di trasparenza dei certificati, i record DNS o i database di intelligence sulle minacce rilevano modifiche.
  • schedule.run.queued: si attiva quando lo scheduler accoda una nuova scansione. Utile per l'orchestrazione CI.

Forma del carico utile

Per ogni consegna viene utilizzata la stessa busta: <code>id</code>, <code>type</code>, <code>created_at</code> e <code>data</code> specifica per l'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 firma l'esatto corpo grezzo JSON con HMAC-SHA-256. Verificare la firma prima di analizzare o considerare attendibili i dati degli eventi. Intestazioni:

  • fixvibe-signature: t=<timestamp>,v1=<hex hmac>
  • fixvibe-event: scan.completed
  • fixvibe-delivery: <uuid> (chiave di idempotenza)
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

Qualsiasi risposta non 2xx, timeout, errore DNS o rifiuto di sicurezza della consegna viene ritentato con backoff esponenziale per circa 24 ore. Le righe di consegna mostrano lo stato della risposta, un breve estratto della risposta, il conteggio dei tentativi e lo stato dei messaggi non recapitabili in Account → Webhook.

Webhook — Docs · FixVibe