AI API Webhook 怎么接收？验签、重复回调与结果写入验收
模型任务回调的正确顺序是：原始请求体验签与时间戳检查、可靠保存事件、返回接收成功，再由后台取回并验收结果。 HTTP 2xx 只确认接收；同一事件再次送达、后台处理失败、旧结果晚到，都需要独立处理，不能直接覆盖业务数据。
本文以 OpenAI 已支持的 Webhooks 为例，官方资料核对日期为 2026 年 11 月 5 日。接收流程和验收表是实施建议，没有执行真实回调。云岚API是否提供供应商原生 Webhook 尚未确认，不能根据模型接口兼容性推定支持。
先确认你需要的是任务回调
Webhook 是服务在事件发生后，向你配置的地址发送通知。例如异步响应完成后，应用再读取输出。它与外部系统触发工作区 Agent方向不同；也不负责Batch 文件逐条配对。先确认目标服务支持的事件、项目范围、签名协议和结果读取方式。OpenAI Webhooks 指南
接收地址应直接指向最终处理路径。OpenAI 当前对超时或非 2xx 响应最多重投 72 小时，采用指数退避；3xx 跳转也视为失败。这个窗口不是业务完成时限，更不是结果一定保留 72 小时的承诺。投递与重试规则
验签需要保留什么？
保存接收到的原始请求体，交给官方 SDK 的验签方法；不要先解析 JSON、重新序列化，再用改变过的文本验签。同时传入原始请求头，使用该接收端点的 signing secret。这个签名密钥与调用模型用的 API Key 分开管理。官方验签示例
验签还检查时间戳是否新鲜。缺少必要头、签名错误或时间超出允许窗口，应拒绝执行后续业务；排查时检查服务器时间、端点密钥和请求体是否被中间件修改，不通过关闭验证来“修好”。通过验签不代表只会收到一次：同一签名请求在有效窗口内仍可能多次通过。SDK 对时间戳和重复处理的说明
快速返回 2xx，为什么还要先保存？
建议把接收端做成短流程，把模型结果读取、文档写入等工作放到后台：
- 验签通过后，校验事件结构和类型，提取已验证的
webhook-id。 - 用“接收端点范围 + webhook-id”建立持久化唯一键，原子保存必要事件内容与待处理状态。
- 数据库提交成功，或可靠队列确认持久接收后，才返回 2xx。
- 后台 worker 领取任务，记录处理中、重试和完成状态。
这里的“保存”不能只是写日志、放进内存或启动一个临时线程。数据库不可用、队列拒收时，不应返回成功造成事件丢失；应暴露接收失败并告警。若先写数据库再另发队列，需有同事务待投递记录和补投机制，避免两步之间崩溃丢任务。这是本文建议的可靠接收设计。
重复事件若已可靠入库，可以确认接收，但必须保留未完成任务的恢复路径。不要把“事件已收到”标记当作“业务已完成”，否则 worker 失败后，后续重投可能被全部跳过。
事件去重和业务幂等，要用两种标识
| 标识 | 解决的问题 | 建议保存的内容 |
|---|---|---|
| 接收端点范围 + webhook-id | 同一投递事件被反复接收 | 原始事件引用、接收时间、处理状态 |
| 业务记录 ID + 输入版本 + 动作类型 | 不同事件或重试导致同一业务动作重复 | 目标位置、动作状态、结果证据 |
去重记录应由各 worker 共享并持久保存。“先查没见过，再插入”存在并发竞争；内存集合无法跨重启、跨副本协调。保留多久应覆盖实际重投和人工重放策略，不能只按验签时间窗口清理。官方持久化去重建议
例如，假设文档 doc-42 的第 3 版摘要需要写入知识库。即使后台重复领取同一任务，目标动作仍使用 doc-42 / v3 / 写摘要 这组稳定标识。数据库内的动作记录与业务更新应保持事务一致；外部系统则需持久化待发送动作，并使用接收方实际支持的幂等机制。若外部写入结果未知且没有可核对的去重机制，转人工核对，不声称保证“恰好一次”。
后台取回结果时，还要核对归属与版本
以 response.completed 为例，事件中的 data.id 指向响应，后台可通过 responses.retrieve 读取。不要把通知体当作完整答案，也不要因为事件名称带 completed 就跳过内容验收。响应读取接口
建议在创建模型任务时就记录：供应商与项目、响应 ID、业务记录、输入版本和预期动作。收到事件后按这张映射核对；未知 ID、项目不符或输入版本已被替换，先隔离复核。结果仍需检查状态、内容和必需字段，可继续使用结构化输出验收。
不要直接按事件到达顺序覆盖状态。若第 3 版摘要晚于第 4 版返回，保留第 3 版记录，但不覆盖当前正文；状态冲突时回查服务端对象，再按业务版本规则决定动作。取回暂时失败，只重试取回阶段，不立即重新生成模型任务。
回调投递窗口与结果保留窗口分别设置。应按项目的实际存储配置及时取回结果，仅保存业务所需内容；不能等到回调重试窗口结束才处理。Background 的存储与查询条件
上线前，至少验收这六种情况
以下是测试计划，不是已经通过的测试记录。可在隔离环境使用供应商提供的测试事件，或按其测试方式构造样例。
| 情形 | 要观察的通过条件 |
|---|---|
| 正常回调 | 可靠入库后才 2xx，结果对应原任务，业务动作有证据 |
| 签名错误或时间戳过期 | 不进入业务处理，不写目标数据 |
| 同一事件并发或重启后重投 | 只有一份接收记录，未完成任务可恢复，业务不重复写入 |
| 数据库或队列不可用 | 不虚报接收成功，恢复后能处理重新投递 |
| worker 取回或写入中途失败 | 从未完成阶段恢复，不因已收到标记丢任务 |
| 旧版本、乱序或归属不符 | 不覆盖新版本，冲突隔离并保留核对记录 |
下载 Webhook 接收与业务验收表。表中只预填六种情形和预期判据；实际状态、响应码、证据与结论留空。它不会发送请求，也不包含密钥。出现模型请求超时，另按超时与重复请求排查定位，避免混淆投递重试和模型重跑。
目标模型接口没有 Webhook 时怎么办？
先查服务是否提供任务查询；若没有，可由自己的持久任务队列安排调用和结果保存，处理完成后通知业务系统。供应商回调与自建队列是不同能力，不能给普通请求加一个回调地址就默认生效。
如果你选择自建队列调用模型，云岚API可作为模型接入选项。先核对当前模型与协议，确认所需接口后注册云岚API，按入门教程验证基础请求，再实现任务状态和通知。已有账号直接进入控制台。这条路径不承诺云岚API提供上述供应商原生 Webhook。