概览
对于异步（async）请求和事件驱动（event-driven）的工作流，ModelRiver 会通过 webhooks 将已完成的 AI 响应通知给您的后端。时间线（Timeline）捕获了每一次交付尝试，包括发送出去的 payload、您服务端点的响应、交付状态以及重试信息。这让您能完全了解您的后端是否确实接收到了 AI 的响应。
Webhook 交付如何显示
在时间线（Timeline）中
- 位置：在主请求之后
- 徽章颜色：
- 灰色 (Gray) – 已计划 (Planned，已排队，尚未发送)
- 蓝色 (Blue) – 交付中 (Delivering，HTTP 请求进行中)
- 绿色 (Green) – 成功 (Success，已成功送达)
- 红色 (Red) – 错误 (Error，交付失败)
- 徽章内容：Webhook URL 与状态
点击后显示内容
点击 webhook 交付会展示：
状态信息
- 交付状态 (Delivery status) – 交付的当前状态 (Planned, Delivering, Success, Error)
- 回调状态 (Callback status) (仅限事件驱动工作流)：
- Progress (进行中) – 期待收到回调，当前尚未收到
- Success (成功) – 已收到回调
- Error (错误) – 回调指示为错误状态或已超时
- 重试按钮 (Retry button) – 在交付失败且允许重试时可用
交付元数据 (Delivery metadata)
| 字段 | 描述 |
|---|---|
| Webhook URL | 接收（或应当接收）webhook 的目标端点 |
| 交付时间 (Delivery time) | webhook 何时被发送（相对时间） |
| 时长 (Duration) | HTTP 请求花费的时间 |
| HTTP 状态码 (HTTP status code) | 来自您端点的响应状态码 |
| 错误消息 (Error message) | 交付失败时的具体错误详情 |
Request Data 选项卡 (webhook payload)
展示确切发送给您的 webhook 端点的 payload 内容：
- 原始 JSON 视图 – 完整的 webhook payload
- 预览模式（树状视图） – 交互式的 JSON 树
- 复制按钮 – 复制 payload 代码以供后续测试或调试
Response 选项卡 (webhook response)
展示从您的 webhook 端点返回的响应：
- 原始视图 – 完整的 HTTP 响应体
- 预览模式（树状视图） – 如果响应内容是 JSON 格式的话
- 复制按钮 – 复制响应以供分析
Webhook 交付生命周期
状态进展
已计划 (Planned) → 交付中 (Delivering) → 成功 (Success) → 错误 (Error) → (重试/Retry) → 交付中 (Delivering) → 成功 (Success) → 错误 (Error)状态详解
-
Planned (已计划) – Webhook 在队列中并已被安排进行交付。这是 AI 响应准备就绪即将发往您的后端时的初始状态。
-
Delivering (交付中) – 指向您端点的 HTTP 请求正在进行中。ModelRiver 正试图发送 webhook payload。
-
Success (成功) – 您的端点返回了一个
2xx状态码。这意味着交付完成，您的后端已经成功接收了 AI 响应。 -
Error (错误) – 交付失败。常见的原因包括：
- 连接被拒 (Connection refused) – 您的端点宕机或是连接不可达
- 超时 (Timeout) – 您的端点响应过慢
- 非 2xx 响应 (Non-2xx response) – 您的端点返回了报错标识 (比如 4xx, 5xx)
- 网络错误 (Network error) – DNS 解析失败，SSL 安全问题等
重试功能
自动重试
ModelRiver 默认会使用指数退避（exponential backoff）算法自动重试失败的 webhook 交付。
手动重试
您可以在“请求日志”详情视图中进行手动重试，需满足以下条件：
can_retry为true- 上次交付状态为失败 (
success状态为false) - 距离上次交付尝试发出已至少经过了 30 秒
重试规则
| 规则 | 详情 |
|---|---|
| 最大尝试次数 | 总共 3 次（最初请求 + 2 轮重试） |
| 时间效期窗口 | 从第一次交付尝试计算的 5 分钟之内 |
| 最小延迟 | 每次尝试之间至少间隔 30 秒 |
| 无重复重试 | 一旦某个交付记录被触发过重试，它自身便不能再被视作下一次的重试源头 |
为什么会有这些规则
- 最大 3 次限制 – 预防水龙头无限循环带来的机器资源过载耗尽
- 五分钟窗口 – 保障在重试时该数据依然具有时效与业务相关性；积压发出的陈旧数据极可能带来混乱
- 30 秒停顿 – 遏止那种能在瞬间将你服务端击垮的重试风暴
- 防重复处理 – 每次重试均会衍生出新的专属交付记录条目，避免造成查漏补缺时的追踪泥潭
如何进行手动重试
- 导航至请求日志 (Request Log) 详情界面
- 单击时间线结构中的那一项 webhook 交付
- 如果 Retry (重试) 按钮显示为可用，点击它
- 会新建出一次全新的交付投递并把它列入队列
- 刷新该详情页面即可察看新创建的投递实况进度
故障排查 (Troubleshooting) Webhook 交付
连接被拒 (Connection refused)
症状：报错消息出现 "connection refused" 或者 "ECONNREFUSED"
原因：您的 webhook 端点根本没有在运行，或它屏蔽了 ModelRiver 服务器集群对它的造访访问。
解决策略：
- 请首要确认您的业务节点真跑起来了并在网络层面允许访客连入
- 核对安全防火墙的设置（放行 ModelRiver IP）
- 若您正在使用自建的极客局域网来调试服务，请确保它配置了内网穿透而能被公网寻址发现 (善用 ModelRiver CLI 本地化调试神器)
超时 (Timeout)
症状：提示为 "timeout" 或是记录显示的执行时间长得离谱
原因：您的端点吞入这笔 webhook 后运算花去的时间超额了。
解决策略：
- 尽可能重构您的 webhook 控制器层以便能尽速抢占式给出应答 (最迟 < 5 秒内)
- 把那些吃性能或需要花时间的计算移至后端后台系统任务表，先行强制给 webhook 回掷一个 200 代码
- 若本身并发量大受制于机器抗压能力太小，请提升节点算力规模配置
非 2xx 响应 (Non-2xx response)
症状：返回了诸如 4xx 或是 5xx 的 HTTP 状态码
原因：您的节点发脾气了，它拒绝接受这单请求。
解决策略：
- 调取您端点服务端内部机器日志以详探它的具体报错堆栈
- 核实该 Webhook 的 Payload 数据外形（形如 JSON 的树结构）合乎你们系统的胃口期盼
- 确保其认证体系（比如 token header 这块如果你们有加的话）未把咱们拦截掉
- 使用工具软件（例: curl 或是 Postman）手提复制来的原始 Payload 直接叩门，测看回响
SSL/TLS 问题错误
症状：附带 SSL、TLS 或证书一类关键词的连线警告
原因：主要就是您的端点机器上面的证书链出了状况。
解决策略：
- 核审该域名上绑覆的证书还没到过期失效的时候
- 确定端点的证书确系正规大型可信颁布局 (CA) 下发，而非随便糊弄一张
- 有没有丢掉配写某些必要的居间商补充证书？务必全数正确串接
检查 Webhook Payloads（负载有效载荷）
为什么审查 Payload 很重要
彻底参透了 webhook 的 payload 构造，会极大帮助您：
- 佐证格式 – 确认您的处理器代码逻辑确实是按照标准协议框架来写
- 捕捉暗藏缺陷 – 准确定位发货 payload 与接货处理程序之间的认知错位
- 终端自治实测 – 全量拷贝一份带有现场案发数据的 payload 以助在地端无缝模拟复刻
- 统御业务流水脉络 – 深察哪些字面信息真真实实流往了你的库房数据库
关键的 Payload 核心字段
以标准规格的异步 (async) Webhook 形式为例：
type– 该事件所属事件类型的称呼 (e.g.,"task.completed","task.ai_generated")data– 生成出的属于 AI 得出智囊数据主核channel_id– 分发到具体这一桩异步事务生命周期里的唯一认证烙印码符
如果这属于事件驱动架构特化的流程 (Event-driven workflows)：
callback_url– 指令要求您的业务后端干完活必须归还复命时所需的那个 API 特配终点 URL 地址- 附加带有专属事件流程所需定制的多道数据参数
下一步
- 后端回调 – 当 webhook 发送过后还会接连发生什么
- Webhooks 文档 – 关于 webhook 全域总括全指导
- 供应商故障转移 – 更早一环节中的失败的供应商回滚探针
- 调试 – 全集式调试大成之作
- 返回时间线 – 退回浏览起点的总览目录页