結論先說
- 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 條評論
還沒有評論,來搶沙發~