重试策略
ModelRiver 使用如下指数退避时间表：
| 尝试次数 | 延迟 | 累计时间 |
|---|---|---|
| 1 | 立即 | 0s |
| 2 | 5 秒 | 5s |
| 3 | 30 秒 | 35s |
| 4 | 2 分钟 | 2m 35s |
| 5 | 10 分钟 | 12m 35s |
| 6 | 30 分钟 | 42m 35s |
| 7 | 1 小时 | 1h 42m 35s |
| 8 | 2 小时 | 3h 42m 35s |
8 次都失败后，该 webhook 会被移入 Dead Letter Queue (DLQ)，供人工排查。
成功投递
你的端点应返回 2xx 状态码（推荐 200 OK）来确认已成功接收。只要返回任意 2xx，ModelRiver 就不会继续重试。
触发重试的情况
以下任一情况都会导致重试：
- 返回非 2xx 状态码（4xx、5xx）
- 网络超时（默认 30 秒）
- 连接被拒绝或 DNS 解析失败
- TLS 握手失败
监控 Webhooks
所有 webhook 投递都会记录在项目的 Request Logs 中：
- Timeline view 展示每次投递尝试与时间戳
- 状态标识 区分成功、失败和待重试
- Payload inspection 可查看实际发送的数据
- Callback logs（事件驱动工作流）可查看你后端的回调结果
你可以按 event_name 过滤日志，以定位特定事件驱动工作流。
死信队列（DLQ）
当所有重试都耗尽后：
- 该投递会移入 DLQ
- 原始载荷会被保留，供排查使用
- 你可以在控制台手动重新投递
- DLQ 条目默认保留 30 天
最佳实践
- 快速响应：尽快返回
200 OK，将实际处理放入后台任务 - 实现幂等性：使用
channel_id去重，因为重试会重复投递同一载荷 - 监控投递成功率：在可观测性中跟踪 webhook 成功率，尽早发现问题
- 做健康检查：持续监控 webhook 端点可用性
- 记录失败详情：把非 2xx 响应与错误原因写入日志
下一步
- 标准 Webhooks：查看载荷结构
- 签名验证：保护你的端点
- 可观测性：观察投递时间线