Webhook 与提醒概览
订阅 PipAI 事件，事件以经过签名的 HTTPS POST 形式投递到你的端点。使用 Webhook 可以无需轮询即可对策略事件、提醒以及账户状态变化做出响应。
本模块涵盖：
- 注册和管理 Webhook 订阅。
- 负载格式与事件类型。
- 校验签名以确认发送方可信。
投递语义
Webhook 投递为 至少一次。PipAI 保证每个事件至少会被投递到健康端点一次，但在重试或瞬态故障期间，同一事件可能会到达多次。
当你的端点在收到请求后的 10 秒内返回 2xx HTTP 状态时，本次投递视为成功。任何其他结果——非 2xx 响应、TLS 错误、连接被拒或超时——都会安排重试。
重试遵循固定的指数退避计划：
| 尝试次数 | 距上次尝试的延迟 |
|---|---|
| 2 | 1 秒 |
| 3 | 5 秒 |
| 4 | 30 秒 |
| 5 | 2 分钟 |
| 6 | 10 分钟 |
| 7 | 30 分钟 |
| 8 | 2 小时 |
| 9 | 6 小时 |
| 10 | 24 小时 |
自原始事件时间起 24 小时之后，PipAI 将放弃投递，该事件会被永久从该 Webhook 的队列中丢弃。
并发
向同一个 Webhook 的投递 不 严格保持顺序。PipAI 并发派发事件以最大化吞吐量，重试也可能让事件相对原始创建时间发生重新排序。
如果你的处理逻辑依赖顺序——例如，需要先处理 strategy.position_opened 再处理对应的 strategy.position_closed——请使用 data 负载中嵌入的事件级排序提示（例如 opened_at、closed_at，或在存在时使用 seq 字段）。不要依赖到达顺序。
注意，并非每个事件类型都带有 seq。当顺序很重要但没有 seq 时，请按事件的 created_at 时间戳结合相关实体 ID 进行排序。
幂等性
由于投递为至少一次，你的处理函数必须具备幂等性。推荐做法是：
- 从事件请求体中读取
id字段（或者从X-PipAI-Event-Id请求头中读取——二者完全相同）。 - 在一个具有 24 小时 TTL 的短期缓存或数据库表中查找该 ID。
- 如果已经见过，立即返回
200 OK并跳过处理。 - 否则，处理事件，并在返回
200 OK之前记录该id。
24 小时的去重窗口已经绰绰有余——PipAI 永远不会在该范围之外重试。
TLS
Webhook 的目标 URL 必须使用 https://。普通的 http:// URL 会在注册时被拒绝并返回 400 INVALID_PARAMETER。
你的端点提供的 TLS 证书必须能链接到一个公开受信任的根证书。自签名证书、过期证书以及主机名不匹配的证书会在投递时被拒绝并计为失败。
状态自动暂停
每个 Webhook 都会跟踪一个 consecutive_failures 计数器。每次投递失败（在全部 10 次尝试用尽之后）该计数器加 1，并在下一次成功投递时重置为 0。
当 consecutive_failures 达到 50 时，Webhook 会自动转为 broken 状态，投递停止。在被手动重新启用之前——通过（即将推出的）PATCH 端点，或者通过对 测试 Webhook 的成功调用（在 2xx 响应时会清零计数器）——该 Webhook 不会再接收新事件。
这一保护机制可防止 PipAI 持续敲打一个永久不可用的端点，并防止队列无限增长。