FixVibe

// docs / webhooks

Webhooks

FixVibe 發送已簽署的出站 Webhook，用於掃描完成、終端故障、高嚴重性結果、即時監控警報和計劃運行。至少交付一次，並在大約 24 小時內重試。

Setup

開啟Account → Webhooks，建立HTTPS端點，並將一次性whsec_秘密儲存在您的接收器中。 Webhook 可在付費方案中使用。

  1. 從Account → Webhooks 建立端點。
  2. 選擇 FixVibe 應傳送到該端點的事件。
  3. 立即複製機密；它僅顯示一次並且只能稍後旋轉。

Events

啟動事件介面涵蓋了團隊通常連接到 CI、警報或票務的時刻：

  • scan.completed — 當掃描轉換到 completed 時觸發。有效負載：掃描 ID、目標、模式、嚴重性桶計數、報告連結。
  • scan.failed — 終端故障通知。有效負載：掃描 ID、失敗原因和報告連結（如果可用）。
  • finding.created — 根據關鍵或高發現排放。預設情況下，較低的嚴重性會折疊為 scan.completed 以避免事件垃圾郵件。
  • monitor.alert.fired — 當憑證透明度日誌、DNS 記錄或威脅情報資料庫偵測到變更時，觸發 Unlimited 計畫。
  • schedule.run.queued — 當調度程式將重新掃描排入佇列時觸發。對於CI 編排很有用。

有效載荷形狀

每次交付都使用相同的信封：<code>id</code>、<code>type</code>、<code>created_at</code> 和事件特定的<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-..."
    }
  }
}

Signing

FixVibe 以HMAC-SHA-256 簽署確切的原始JSON 主體。在解析或信任事件資料之前驗證簽章。標題：

  • fixvibe-signature: t=<timestamp>,v1=<hex hmac>
  • fixvibe-event: scan.completed
  • fixvibe-delivery: <uuid> （冪等性金鑰）
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

任何非 2xx 回應、逾時、DNS 失敗或交付安全拒絕都會以指數退避方式重試約 24 小時。交付行在帳戶 → Webhooks 中顯示回應狀態、簡短回應摘錄、嘗試計數和死信狀態。