通知 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. 载荷结构

每次送达都是一个以 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 请求的响应中返回。请立即保存它。此后，列表端点和有效配置端点只会报告该偏好存在密钥（hasWebhookSecret: true）；它们绝不会再次返回该值，之后也没有任何途径可以取回。对同一事件类型的后续 upsert 会复用现有密钥，而不是生成新的。

8. 验证签名

使用签名密钥来确认某次送达确实来自 Stratum，且未被篡改或重放。对每个签名请求：

读取 X-Stratum-Timestamp（Unix 秒）和 X-Stratum-Signature（格式为 v1=<hex>）。
用一个英文句点连接时间戳和原始请求体，构造待签名字符串：<timestamp>.<raw body>。
以你的密钥为 key，对该字符串计算 HMAC-SHA256，并将结果进行十六进制编码。
使用恒定时间比较，将你的十六进制摘要与 v1= 之后的值进行比对。如不匹配，则拒绝该请求。
拒绝时间戳早于你的容忍范围的请求，以防范重放攻击。

请对你接收到的确切字节计算 HMAC，先于任何 JSON 重新序列化。