OpenAI Webhook 怎么验签与去重:后台任务回调只处理一次

按 OpenAI 官方 Webhook 规范,保留原始请求体验签、用 webhook-id 去重,再以短响应和后台队列处理异步结果。

关键词
LALondAI 内容团队发布日期 2026-11-20
6 分钟阅读模型教程
LA
OpenAI Webhook 怎么验签与去重:后台任务回调只处理一次
OpenAI Webhook官方来源与可执行检查LondAI 内容团队

接收 OpenAI 后台响应或 Batch 完成通知时,先校验回调签名,再做持久化去重,最后交给后台任务取回结果。收到 response.completed 并不等于本站用户余额、订单或业务记录已经处理完成;回调也可能重复送达。

官方回调提供了哪些信息

OpenAI Webhooks 指南给出的通知包含 webhook-id、webhook-timestamp、webhook-signature,事件体另有事件 ID、类型和 data.id。创建端点时选择事件类型,并把一次性显示的签名密钥保存在服务端安全配置中。OpenAI 建议用官方 SDK 的 webhooks.unwrap() 同时验签和解析;请求体须保留接收时的原始字节,先重新序列化 JSON 再验签可能导致校验失败。

为何回 200 前必须完成去重入队

官方说明非 2xx、超时或 3xx 都会被视作失败,最长可在 72 小时内指数退避重试;少数情况下同一事件也可能重复投递。建议用 webhook-id 做数据库或队列的唯一键:首次验签通过后原子地记录该 ID 和事件类型,入队成功再迅速返回 2xx;重复 ID 直接返回 2xx,不再次触发业务写入。若入队未成功就回 2xx,通知可能永久丢失。此处是实现建议,具体存储方案须由业务系统选择。

最小处理流程

  1. 为独立的公网 HTTPS 路径配置 OpenAI Webhook 端点,订阅实际需要的完成或失败事件;确认没有 301/302 跳转,且服务端配置了签名密钥。
  2. 在路由最前面读取原始请求体与三个 Webhook 头,用官方 SDK 验签;签名或时间戳不通过时返回 4xx,不进入业务队列。不要输出密钥或完整原文到日志。
  3. 用 webhook-id 原子去重后保存事件类型和资源 ID,将处理任务入队;成功入队就快速返回 2xx,重复投递不再次入队。
  4. 消费者按事件类型取回最终资源,核对其 ID、状态与提交时记录的任务关联,再更新本地状态。后台请求的轮询与取回可参照2h/8h 后台任务指南。

签名正确不等于业务可重复执行

OpenAI TypeScript SDK 参考要求验签使用原始 JSON 字符串。签名证明请求来源,无法替代业务幂等;同一资源可能有不同类型的事件,处理时还应核对任务 ID 与终态,写入步骤要能安全重放。本文仅说明 OpenAI 官方接口及实现建议,未声称 LondAI 当前已开通 Webhook,也没有修改本站网关、支付或数据库。

上线前做四次回放

用测试端点验证有效签名进入队列一次、篡改正文被拒、同一 webhook-id 重送不重复处理、队列故障返回非 2xx 后重送可恢复。检查资源最终状态与任务提交记录一致,日志只保留必要事件 ID 和耗时。接入站点的基础接口说明见 LondAI 文档;实际账单仍须单独对照供应商与本站使用记录。