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

图:本站根据 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),配置步骤如下:
- 登录 OpenAI Platform,切换到目标项目,进入 设置(Settings)> Webhooks;
- 点击 创建(Create),填入公网可达的
https://接收地址(不支持纯 HTTP 明文地址); - 勾选要订阅的事件类型,常见高频事件如下:
| 业务模块 | 常用订阅事件名 | 触发时机与后续动作 |
|---|---|---|
| 批量接口(见 /guides/openai-api-batch) | batch.completed、batch.failed、batch.expired | 24 小时内批处理结束,凭 data.id 拉取输出文件 ID |
| 后台长推理(见 /guides/openai-responses-api) | response.completed、response.failed | 开启 background=True 的深度研究或长链推理执行完毕 |
| 模型微调与评测 | fine_tuning.job.succeeded、eval.run.succeeded | 训练权重就绪或自动化评测跑完,可触发上线通知 |
- 提交后复制页面弹出的签名密钥(以
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 充值,免交密码即可完成兑换。
三、验签报错与重复投递排查决策

图:本站根据 OpenAI 官方文档:Webhooks 整理的示意图
遇到回调链路异常时(常见 HTTP 状态码含义见 /guides/openai-api-error-codes),重点排查三处:
- 签名始终不匹配:确认传入
unwrap的第一个参数是原始字符串(Node.js Express 需对该路由单独使用express.raw而非全局express.json),且OPENAI_WEBHOOK_SECRET与当前发起任务所在的 Project 一一对应。 - 时间戳校验过期:Standard Webhooks 会将
webhook-timestamp与本机当前时间比对(默认容忍 5 分钟偏差)。若容器时钟漂移,需用 Chrony 或 NTP 同步宿主机时间。 - 同一任务收到多次回调:若你的接口在返回
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
0 条评论
还没有评论,来抢沙发~