通知 Webhook

Stratum 可以將你的融資自動化事件 POST 至你所掌控的 HTTPS 端點。Webhook 是一種通知通道：你為在意的事件類型啟用它，Stratum 便會將每個事件以 JSON 請求送出，讓你能將其導入自己的工具、警示或儀表板。這是對應用程式內與電子郵件通知的補充，而非取代圍繞你的受限範圍 Bitfinex API 金鑰所建立的安全模型。

1. 啟用 Webhook 通道

通知傳遞是依事件類型與通道分別設定的。若要開始接收 Webhook，請向 PUT /api/v1/settings/notifications 送出偏好設定的 upsert，內容如下：

type — 你想要傳遞的事件類型（見下方清單）。
channel — WEBHOOK。
enabled — true。
webhookUrl — 你的 HTTPS 端點（最多 2048 個字元）。

若要查看目前的設定，GET /api/v1/settings/notifications 會列出你明確設定的偏好，而 GET /api/v1/settings/notifications/effective 會回傳設定畫面所根據的「預設值加覆寫」合併檢視，其中包含你的 webhookUrl 以及一個 hasWebhookSecret 旗標。

2. 端點需求

你的 URL 必須使用 https。Stratum 在你儲存時以及實際傳遞時都會驗證該 URL，並拒絕指向 localhost 或內部／私有網路位址的端點。重新導向不會被跟隨——請求會送往你所設定的確切 URL。你的端點應以 2xx 狀態回應；任何其他回應都會被視為傳遞失敗並重試。

3. 可路由的事件類型

下列事件類型可傳遞至 Webhook：

RATE_SPIKE、RATE_DROP、RATE_FLOOR_BLOCKED
LOAN_EXECUTED、LOAN_EXPIRING、LOAN_EARLY_REPAID、LARGE_EARLY_REPAYMENT、LARGE_LOAN_FILLED
STALE_OFFER
KILL_SWITCH_ACTIVATED、STRATEGY_PAUSED、STRATEGY_ERROR、STRATEGY_TICK_STALE
API_KEY_INVALID、API_KEY_PERMISSIONS_CHANGED
PLATFORM_OUTAGE、PLATFORM_RECOVERED、SYSTEM_ALERT
LOW_UTILIZATION、IDLE_CASH、FEE_TIER_CHANGED
DAILY_DIGEST、WEEKLY_DIGEST、MONTHLY_DIGEST、YEARLY_DIGEST

有少數事件類型不在設定中依通道切換——HIGH_UTILIZATION、OFFER_FILLED、EARNINGS_MILESTONE 與 WITHDRAWAL_DETECTED 由系統為你管理，不開放 Webhook 訂閱。週期性摘要（DAILY_DIGEST 至 YEARLY_DIGEST）預設以電子郵件傳送；若你也想讓它們透過 Webhook 傳遞，請明確啟用 Webhook 通道。

4. Payload 結構

每次傳遞都是一個以 Content-Type: application/json 送出的單一 JSON 物件：

type — 事件類型名稱，例如 LOAN_EXECUTED。
severity — INFO、WARNING 或 ERROR 其中之一。
title — 簡短的人類可讀標題。
body — 人類可讀的訊息。
createdAt — ISO-8601 時刻。
payload — 包含特定類型欄位的物件；可能為空。
userId — 你的數字使用者 ID。

例如（欄位值僅供示意）：

{"type":"LOAN_EXECUTED","severity":"INFO","title":"Loan executed","body":"A funding offer was filled.","createdAt":"2026-05-31T12:00:00Z","payload":{},"userId":1}

5. 標頭

每個請求都會帶有：

X-Stratum-Type — 事件類型名稱（與內文 type 的值相同）。
User-Agent — Stratum/<version> (+https://stratum.money)。

當你設有簽章密鑰時，每個請求還會包含 X-Stratum-Timestamp 與 X-Stratum-Signature（見下方的簽章驗證）。

6. 傳遞與重試

Stratum 最多等待 5 秒讓你的端點回應。若傳遞失敗——非 2xx 回應、逾時或連線錯誤——便會以指數退避重試。總共最多有 6 次傳遞嘗試，連續嘗試之間的延遲為 1 分鐘、5 分鐘、15 分鐘、1 小時與 4 小時。排程器大約每 60 秒會取出到期的重試。請將你的端點設計為冪等，這樣同一事件被重試傳遞時不會造成問題。

7. 簽章密鑰

Webhook 偏好是依事件類型分別儲存，每一筆都帶有自己的簽章密鑰。當你首次為某個事件類型啟用 Webhook 通道時，Stratum 會產生該密鑰並僅回傳一次——就在該 upsert 請求的回應中。請立即儲存。在那之後，清單與 effective 端點只會回報該偏好存在密鑰（hasWebhookSecret: true）；它們絕不會再回傳該值，事後也無從取回。對同一事件類型後續的 upsert 會沿用既有密鑰，而非產生新的。

8. 驗證簽章

使用簽章密鑰來確認某次傳遞確實來自 Stratum，且未被竄改或重放。對每個帶簽章的請求：

讀取 X-Stratum-Timestamp（Unix 秒）與 X-Stratum-Signature（格式為 v1=<hex>）。
以英文句點將時間戳與原始請求內文相接，組成簽章字串：<timestamp>.<raw body>。
以你的密鑰作為金鑰，對該字串計算 HMAC-SHA256，並將結果以十六進位編碼。
以常數時間比對，將你的十六進位摘要與 v1= 之後的值相比。若不相符，拒絕該請求。
拒絕時間戳對你的容許範圍而言過舊的請求，以防範重放。

請對你所接收到的確切位元組計算 HMAC，且須在任何 JSON 重新序列化之前進行。