OpenAI Webhook 允许您接收有关 API 事件的实时通知,例如批量任务完成、后台响应生成或微调作业结束。Webhook 会发送至您控制的 HTTP 端点,并遵循 Standard Webhooks 规范。Webhook 事件的完整列表可以在 API 参考手册中找到。
查看 Webhook 事件的完整列表。
以下是一些能够接收 OpenAI Webhook 的简单服务器示例,专门针对 response.completed 事件。
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 仪表板中设置一个订阅了 response.completed 的 Webhook 端点,然后发起一个 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 上。
- 云开发环境,如 Replit、GitHub Codespaces、Cloudflare Workers 或 Vercel 的 v0。
验证 Webhook 签名
虽然您可以在没有任何验证的情况下接收和处理 OpenAI 的 Webhook 事件,但您应该验证传入的请求确实来自 OpenAI,特别是当您的 Webhook 会在后端执行任何类型的操作时。随 Webhook 请求发送的标头中包含可与 Webhook 密钥结合使用的信息,用以验证 Webhook 是否源自 OpenAI。
当您在 OpenAI 仪表板中创建 Webhook 端点时,您将获得一个签名密钥,您应将其作为环境变量在服务器上使用。
export OPENAI_WEBHOOK_SECRET="<your secret here>"验证 Webhook 签名最简单的方法是使用官方 OpenAI SDK 辅助工具中的 unwrap() 方法:
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 规范中的描述自行实现签名验证。
如果您丢失或不慎泄露了签名密钥,可以通过轮换签名密钥来生成一个新的。