后端回调 – ModelRiver Docs

概览

后端回调（Backend callbacks）是事件驱动（event-driven）工作流中的关键组成部分。当 ModelRiver 将包含 AI 响应的 webhook 发送给您的后端之后，您的后端会处理这些数据，并通过提供的 callback_url 把结果回调（call back）给 ModelRiver。时间线会跟踪这整个循环，展示您的回调是被接收、超时还是失败了。

后端回调的工作原理

事件驱动工作流

AI 生成响应 → 时间线中的主请求 (Main request)
向后端发送 Webhook → 时间线中的 webhook 交付 (Webhook delivery)，带有 type: "task.ai_generated" 和 callback_url
后端处理数据 → 业务逻辑、数据库操作等
后端发送回调 → 将处理后的数据 POST 到 callback_url
ModelRiver 广播结果 → 通过 WebSocket 通道发送最终响应
记录回调日志 → 后端回调出现在时间线上

Seed 批次标识

后端回调的日志条目具有不同的 seed_batch 值，用来区分请求类型：

"callback:{channel_id}" – 生产级别请求的回调
"pg_callback:{channel_id}" – playground 测试请求的回调

后端回调如何展示

在时间线（Timeline）中

位置：位于 webhook 交付之后（在时间线末尾处）
视觉标识：带有 "Backend Callback" 标签的闪电图标
状态提示：
- Success (成功) – ModelRiver 收到了回调
- Timeout (超时) – 在 5 分钟窗口内未收到回调
- Simulated (已模拟) – 针对 playground 测试，表示该回调为模拟发出

点击后显示内容

点击某个后端回调将展示以下面板：

回调 Payload (Callback payload)

此为后端从 webhook 交付中接收到的数据。与 webhook 交付详细信息中的“Request Data”选项卡内容相同：

原始 JSON 视图 – 完整的 webhook payload
预览模式（树状视图） – 交互式的 JSON 树
复制按钮 – 提供一键复制以便调试

回调响应 (Callback response)

此为您的后端通过 callback_url 发送回 ModelRiver 的数据：

原始 JSON 视图 – 完整的 callback 响应
预览模式（树状视图） – 交互式的 JSON 树
复制按钮 – 提供一键复制以便分析

回调状态

Success (成功)

含义：ModelRiver 在 5 分钟的有效窗口期内成功接收到了您后端发出的回调。

排查建议：

确认回调响应中的数据是否正确
确保最终响应已经被广播到了关联的 WebSocket 通道
验证处理后的数据与您的预期一致

Timeout (超时)

含义：后端未在 5 分钟内成功调用 callback_url。

超时后会发生什么：

ModelRiver 向 WebSocket 通道发送请求超时的报错信息
在日志中记录超时事件
将该请求标记为失败 (Failed)

常见原因：

后端在处理数据时抛出了异常
后端完全没有收到 webhook 交付 (需先检查 webhook 交付状态)
业务逻辑处理时间超过了 5 分钟
后端没有尝试调用 callback_url
网络问题导致回调请求未能最终触达 ModelRiver

如何调试：

首先检查 webhook 交付 (webhook delivery) 的状态：后端是否收到了 webhook？
检查后端服务器日志，看看是否有处理过程报错
验证服务端是否正向正确的 callback_url 发起 POST 请求
检查是否由于超复杂的逻辑导致处理耗时超出 5 分钟限制
验证后端到 ModelRiver 之间的网络连通性

Simulated (已模拟)

含义：回调是 playground 测试的一部分，由系统模拟生成。在 playground 模式下，ModelRiver 会模拟发出回调响应，为您完整展现工作流而不依赖真实的后端服务。

何时出现：仅在使用 playground 测试进行模拟时出现。涉及生产流程的请求绝不会出现此状态。

回调 Payload 格式

后端接收到的内容 (webhook)

webhook 控制器往往会接收到包含以下字段的 payload：

type: "task.ai_generated" – 指示这是一条事件驱动回调请求
data – 包含 AI 生成的具体响应数据
callback_url – 你的后端将处理后数据推送回 ModelRiver 所需请求的 URL
channel_id – 当前异步请求的全局绝对唯一标识符

后端需要发回的内容

后端应向 callback_url 进行 POST，并在请求主体（Body）中包含：

请求主体中包含被处理后的数据
您的应用在后续最终响应中依赖的所有额外字段

调试回调相关的问题

回调未出现在时间线中

可能原因：

Webhook 交付提前失败了：请优先确认 webhook 的状态
你的后端根本没有向提供给你的 callback_url 发起请求
仍在处理中（在 5 分钟的允许接收空窗期内）

回调显示为超时 (Timeout)

单步排查指南：

检查 webhook 交付状态 – 后端真的收到请求了吗？
检查后端服务器日志 – 机器确实对该 webhook 开展了业务处理操作吗？
核实 URL – 目标请求地址 callback_url 拼对了吗？
验证 Payload 是否合理 – 你发送出来的数据，真的符合格式期许吗？
对齐处理时长 – 它是否受某种影响卡在某个函数超过了 5 分钟？

回调已成功但得到的结果不符预期