OpenAI API Webhooks 事件回调怎么配:异步接收 Batch、后台长任务与微调完成通知及签名验签

跑 OpenAI Batch 批量请求或后台长推理任务还在写死循环轮询状态?本文按官方文档讲清 Webhooks 端点配置、支持事件类型、whsec_ 密钥获取,以及用 SDK webhooks.unwrap 完成签名验签与防重放。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. OpenAI Webhooks 采用 Standard Webhooks 规范主动推送异步任务状态。支持批处理(batch.)、后台响应(response.)、微调任务(fine_tuning.job.)及评测(eval.run.)等完成与失败事件。
  2. 验签必须读取未经解析的原始请求体(Raw Body)。一旦 Web 框架中间件把 JSON 解析成字典再重新序列化,空格或键序变动就会导致 HMAC 签名失效。
  3. 官方 SDK 提供一行式 client.webhooks.unwrap 验签解析函数。它会自动比对 whsec_ 开头的签名密钥、核查 webhook-timestamp 防重放窗口,并返回带类型的事件对象。
  4. 接收端点需在数秒内返回 2xx 并做幂等去重。耗时落库或下载结果文件应放入后台队列,并以请求头 webhook-id 作为唯一键防重复执行。
  5. 研发团队在对接 API 之余若需开通日常交互订阅,国内无外币卡用户可在本站自助选购 ChatGPT Plus 或高配额 ChatGPT Pro,多席位协作可了解 ChatGPT Business 团队定制。

OpenAI Webhooks 配置与验签四步

图:本站根据 OpenAI 官方文档:Webhooks 整理的示意图

本文根据 OpenAI API 官方文档《Webhooks》《Batch API》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。

适用于谁

  • 使用 OpenAI Batch API、Responses 后台模式(background=True)或微调(Fine-tuning),不想自己维护定时轮询脚本的后端开发者;
  • 需要用官方 SDK 对回调请求做签名验签(Signature Verification),防止伪造请求打穿内部接口的人;
  • 遇到 webhooks.unwrap 报签名校验失败或收到重复事件推送的排查者。

一、平台后台创建端点与常见事件清单

Webhooks 按项目(Project)维度隔离管理(API 密钥与项目权限基础见 /guides/openai-api-key),配置步骤如下:

  1. 登录 OpenAI Platform,切换到目标项目,进入 设置(Settings)> Webhooks;
  2. 点击 创建(Create),填入公网可达的 https:// 接收地址(不支持纯 HTTP 明文地址);
  3. 勾选要订阅的事件类型,常见高频事件如下:
业务模块常用订阅事件名触发时机与后续动作
批量接口(见 /guides/openai-api-batch)batch.completed、batch.failed、batch.expired24 小时内批处理结束,凭 data.id 拉取输出文件 ID
后台长推理(见 /guides/openai-responses-api)response.completed、response.failed开启 background=True 的深度研究或长链推理执行完毕
模型微调与评测fine_tuning.job.succeeded、eval.run.succeeded训练权重就绪或自动化评测跑完,可触发上线通知
  1. 提交后复制页面弹出的签名密钥(以 whsec_ 开头),存入服务端环境变量 OPENAI_WEBHOOK_SECRET。

二、Python 接收端签名验签与幂等消费代码

下面以 FastAPI 为例,展示读取原始字节流并调用官方 SDK unwrap 完成验签的标准写法:

python
import os
from fastapi import FastAPI, Request, HTTPException, Response
from openai import OpenAI, InvalidWebhookSignatureError

app = FastAPI()
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])
processed_ids = set()

@app.post("/webhooks/openai")
async def openai_webhook(request: Request):
    raw_body = await request.body()
    headers = dict(request.headers)
    try:
        event = client.webhooks.unwrap(
            raw_body.decode("utf-8"),
            headers,
        )
    except InvalidWebhookSignatureError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    msg_id = headers.get("webhook-id", "")
    if msg_id in processed_ids:
        return Response(status_code=200)
    processed_ids.add(msg_id)

    if event.type == "batch.completed":
        batch_id = event.data.id
        print("批处理已完成,待异步下载结果:", batch_id)

    return Response(status_code=200)

生产环境中请将示例里的内存集合 processed_ids 替换为 Redis SET NX 或数据库唯一索引。

订阅与账号准备提示:在编写异步批处理与回调逻辑前,往往需要先在交互端用小样本打磨提示词与评测标准。国内若无境外信用卡,可在本站自助开通 ChatGPT Plus 会员 或升级 ChatGPT Pro 充值,免交密码即可完成兑换。

三、验签报错与重复投递排查决策

Webhook 验签失败与重复投递排查

图:本站根据 OpenAI 官方文档:Webhooks 整理的示意图

遇到回调链路异常时(常见 HTTP 状态码含义见 /guides/openai-api-error-codes),重点排查三处:

  1. 签名始终不匹配:确认传入 unwrap 的第一个参数是原始字符串(Node.js Express 需对该路由单独使用 express.raw 而非全局 express.json),且 OPENAI_WEBHOOK_SECRET 与当前发起任务所在的 Project 一一对应。
  2. 时间戳校验过期:Standard Webhooks 会将 webhook-timestamp 与本机当前时间比对(默认容忍 5 分钟偏差)。若容器时钟漂移,需用 Chrony 或 NTP 同步宿主机时间。
  3. 同一任务收到多次回调:若你的接口在返回 200 之前同步去下载几十兆的 .jsonl 结果文件导致超时,OpenAI 会按退避策略重发通知。务必遵循「先验签入队回 200,后异步拉文件」的原则。

常见问题

问:Webhook 推送的消息体里直接包含模型生成的完整文本或整个批处理结果吗?

答:不包含大体积正文。Webhook 载荷是轻量通知信封(主要含事件类型 type 与资源标识 data.id),验签通过后需用该 ID 再调一次 client.batches.retrieve 或 client.responses.retrieve 拉取完整内容。

问:whsec_ 签名密钥泄露或怀疑失密怎么轮换?

答:回到平台项目设置页的 Webhooks 面板,针对该端点执行密钥轮换(Rotate secret)或新建端点平滑切换,更新线上环境变量后再停用旧端点。

问:国内没有外币卡,或者企业需要开增值税发票报销,怎么开通配套的官方会员?

答:可通过本站 AI 会员充值总览 选购 ChatGPT Plus 或 ChatGPT Pro,支持支付宝、微信支付及 AlipayHK 付款,提供卡密自助兑换与企业定制,并可开具增值税发票。实时价格以页面显示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。

相关教程

参考资料

  • OpenAI API 官方文档:Webhooks — https://platform.openai.com/docs/guides/webhooks
  • OpenAI API 官方文档:Batch API — https://platform.openai.com/docs/guides/batch

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 整理家庭装修预算明细、隐蔽工程验收清单与主材优缺点对比表实战

    第一次装修面对几十页施工报价单、密密麻麻的水电防水隐蔽项目与五花八门的主材参数,极易踩坑增项。本文梳理用 ChatGPT 审查装修报价漏项、生成带公式的预算明细表、定制工地隐蔽工程验收单与主材对比表的实战提示词。

    ChatGPT0
  2. 02

    用 ChatGPT 做费曼学习法读书共读:反向追问检验自己是否真读懂专业书籍与整理书单笔记

    读完一本专业硬书常感觉「合上书就忘」,直接让 AI 概括全书又容易产生懂了的错觉。本文介绍用 ChatGPT 结合 Study Mode 与费曼学习法做反向追问共读,通过通俗复述、挑刺盲区到沉淀书单卡片的完整流程与提示词。

    ChatGPT0
  3. 03

    用 ChatGPT 做外贸产品多语种目录、展会邀约与客户跟进节奏表(附脱敏与本地化提示词)

    做外贸展会与海外推广时,手工翻译十几款产品目录费时且容易留下一堆中式英文,展后客户跟进也常缺节奏。本文梳理用 ChatGPT 先脱敏建术语库、再批量产出多语种目录、展前邀约函与展后 21 天跟进节奏表的实战流程与提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写高质量技术专栏文章、开源项目 Release Notes 与版本更新日志实战

    让 AI 直接凭空写技术文章容易满篇空洞套话,直接甩 Git 记录写更新日志又常常漏掉破坏性变更。本文整理用 ChatGPT 结合真实代码片段、压测数据与 PR 摘要,高效产出深度技术专栏、GitHub Release Notes 与 CHANGELOG 的实战工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做产品用户访谈纪要编码、提炼高频痛点需求池与 RICE 优先级打分实战

    手头攒了十几份用户访谈逐字稿,手工贴便利贴归纳痛点耗时又容易带入主观偏见。本文分享用 ChatGPT 完成脱敏检查、逐份开放式编码、跨样本聚类高频痛点并搭建 RICE 优先级打分表的 5 步实战流,附可直接复制的三段核心提示词。

    ChatGPT0
  6. 06

    ChatGPT 网页版上传超过 10 个文件或回形针附件按钮变灰怎么办:打包合并与配额限制排查

    在 ChatGPT 网页版批量分析文档时,常遇到一次选超 10 个文件被拦截或输入框回形针按钮变灰。本文依据 OpenAI 文件上传与存储说明,梳理 6 类常见报错的分流排查法,提供 ZIP 打包、本地合并与 Projects 复用方案及可直接复制的解包提示词。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~