OpenAI webhooks 允许你接收关于 API 中事件的实时通知,例如批量任务完成、后台响应生成或微调任务结束。Webhook 将按照 Standard Webhooks 规范。完整的 webhook 事件列表可在 API 参考.
查看 webhook 事件的完整列表。
以下是一些能够接收来自 OpenAI 的 webhook 的简单服务器示例,专门用于 response.completed event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import os
from openai import OpenAI, InvalidWebhookSignatureError
from flask import Flask, request, Response
app = Flask(__name__)
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])
@app.route("/webhook", methods=["POST"])
def webhook():
try:
# with webhook_secret set above, unwrap will raise an error if the signature is invalid
event = client.webhooks.unwrap(request.data, request.headers)
if event.type == "response.completed":
response_id = event.data.id
response = client.responses.retrieve(response_id)
print("Response output:", response.output_text)
return Response(status=200)
except InvalidWebhookSignatureError as e:
print("Invalid signature", e)
return Response("Invalid signature", status=400)
if __name__ == "__main__":
app.run(port=8000)要查看类似于此的 webhook 实际运行情况,你可以在 OpenAI 仪表板中设置一个 webhook 端点,并订阅 response.completed, 然后发起 API 请求至 在后台模式下生成响应.
你还可以使用来自以下位置的样本数据触发测试事件 webhook 设置页面.
1
2
3
4
5
6
7
8
9
10
11
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-5.5",
input="Write a very long novel about otters in space.",
background=True,
)
print(resp.status)在本指南中,你将学习如何在仪表板中创建 webhook 端点,设置服务端代码来处理它们,并验证入站请求是否确实来自 OpenAI。
创建 webhook 端点
要开始在您的服务器上接收 webhook 请求,请登录控制面板并 打开 webhook 设置页面。Webhook 按项目进行配置。
点击“创建”按钮以创建新的 webhook 端点。您将配置以下三项内容:
- 端点名称(仅供您参考)。
- 您控制的一台服务器的公开 URL。
- 一个或多个要订阅的事件类型。当这些事件发生时,OpenAI 将向指定的 URL 发送 HTTP POST 请求。
创建新 webhook 后,您将收到一个签名密钥,用于在服务器端验证传入的 webhook 请求。请保存此值以备后用,因为之后您将无法再次查看它。
创建 webhook 端点后,接下来您需要设置一个服务器端点来处理传入的事件载荷。
在服务器上处理 webhook 请求
当您订阅的事件发生时,您的 webhook URL 将收到如下 HTTP POST 请求:
POST https://yourserver.com/webhook
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52
webhook-timestamp: 1750287078
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
"object": "event",
"id": "evt_685343a1381c819085d44c354e1b330e",
"type": "response.completed",
"created_at": 1750287018,
"data": { "id": "resp_abc123" }
}您的端点应快速响应这些传入的 HTTP 请求,并返回一个成功(2xx) 状态码,以指示已成功接收。为避免超时,我们建议将任何非简单的处理工作卸载到后台工作器,以便端点能够立即做出响应。如果端点未返回成功(2xx) 状态码,或者在几秒钟内未响应,webhook 请求将被重试。OpenAI 将以指数退避方式继续尝试投递,最长可达 72 小时。请注意, 3xx 重定向将不会被跟随;它们会被视为失败,因此应当更新您的端点以使用最终目标 URL。
在极少数情况下,由于内部系统问题,OpenAI 可能会投递同一 webhook 事件的重复副本。您可以使用 webhook-id 标头作为幂等键进行去重。
在本地测试 Webhook
测试 Webhook 需要一个公网可访问的 URL。这可能会给开发带来不便,因为您的本地开发环境通常不会对公网开放。以下是一些可能有帮助的解决方案:
- ngrok 它可以在公共 URL 上暴露您的 localhost 服务器
- 云端开发环境,例如 Replit, GitHub Codespaces, Cloudflare Workers, or v0 from Vercel.
验证 Webhook 签名
虽然您无需任何验证即可接收来自 OpenAI 的 Webhook 事件并处理结果,但您应该验证传入请求是否确实来自 OpenAI,尤其是当您的 Webhook 会在后端执行任何操作时。与 Webhook 请求一同发送的请求头包含一些信息,这些信息可以与 Webhook 密钥结合使用,以验证该 Webhook 是否源自 OpenAI。
当您在 OpenAI 仪表板中创建 Webhook 端点时,系统会提供一个签名密钥,您应将其作为环境变量在您的服务器上可用:
export OPENAI_WEBHOOK_SECRET="<your secret here>"验证 Webhook 签名最简单的方法是使用 unwrap() 官方 OpenAI SDK 助手中的方法:
1
2
3
4
5
client = OpenAI()
webhook_secret = os.environ["OPENAI_WEBHOOK_SECRET"]
# will raise if the signature is invalid
event = client.webhooks.unwrap(request.data, request.headers, secret=webhook_secret)也可以使用以下方式验证签名 Standard Webhooks 库:
1
2
3
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);或者,如有需要,您可以按照 Standard Webhooks 规范中的说明,自行实现签名验证
如果您的签名密钥丢失或意外泄露,您可以通过 轮换签名密钥来生成一个新的.