OpenAI の Webhook を使うと、バッチの完了、バックグラウンドでのレスポンス生成、ファインチューニングジョブの終了など、API のイベントに関する通知をリアルタイムで受け取れます。Webhook は、Standard Webhooks 仕様に従って、管理下の HTTP エンドポイントに配信されます。Webhook イベントの全一覧は、API リファレンスで確認できます。
API プロジェクトのミスアラインメントの監視に関する通知を受け取るには、プロジェクトの安全性アラートの受信をご覧ください。
Agents API のセッションイベントと復旧パターンについては、セッションの Webhookをご覧ください。Webhook の受信側には、このページのエンドポイントのセットアップ、署名検証、配信に関するガイダンスを適用してください。
以下に、OpenAI からの Webhook のうち、response.completed イベントを受信できるサーバーの例を示します。
Ruby の例では、
gem install openai webrick で必要な依存関係をインストールしてから、OPENAI_API_KEY と
OPENAI_WEBHOOK_SECRET を設定します。
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39import OpenAI from "openai";
import express from "express";
const app = express();
const client = new OpenAI({ webhookSecret: process.env.OPENAI_WEBHOOK_SECRET });
// Don't use express.json() because signature verification needs the raw text body
app.use(express.text({ type: "application/json" }));
app.post("/webhook", async (req, res) => {
try {
const event = await client.webhooks.unwrap(req.body, req.headers);
if (event.type === "response.completed") {
const response_id = event.data.id;
const response = await client.responses.retrieve(response_id);
const output_text = response.output
.filter((item) => item.type === "message")
.flatMap((item) => item.content)
.filter((contentItem) => contentItem.type === "output_text")
.map((contentItem) => contentItem.text)
.join("");
console.log("Response output:", output_text);
}
res.status(200).send();
} catch (error) {
if (error instanceof OpenAI.InvalidWebhookSignatureError) {
console.error("Invalid signature", error);
res.status(400).send("Invalid signature");
} else {
throw error;
}
}
});
app.listen(8000, () => {
console.log("Webhook server is running on port 8000");
});
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
26
27import 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)
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48require "openai"
require "webrick"
client = OpenAI::Client.new(
webhook_secret: ENV.fetch("OPENAI_WEBHOOK_SECRET")
)
server = WEBrick::HTTPServer.new(
BindAddress: "127.0.0.1",
Port: Integer(ENV.fetch("OPENAI_WEBHOOK_PORT", "8000")),
Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN),
AccessLog: []
)
response_workers = []
server.mount_proc("/webhook") do |request, response|
if request.request_method != "POST"
response.status = 405
next
end
headers = request.header.transform_values(&:first)
event = client.webhooks.unwrap(request.body, headers)
if event.is_a?(OpenAI::Models::Webhooks::ResponseCompletedWebhookEvent)
response_workers.select!(&:alive?)
response_workers << Thread.new(event.data.id) do |response_id|
completed_response = client.responses.retrieve(response_id)
puts "Response output: #{completed_response.output_text}"
end
end
response.status = 200
response.body = "ok"
rescue OpenAI::Errors::InvalidWebhookSignatureError, ArgumentError => error
warn "Invalid signature: #{error.message}"
response.status = 400
response.body = "Invalid signature"
ensure
server.shutdown if ENV["OPENAI_WEBHOOK_EXIT_AFTER_REQUEST"] == "1"
end
Signal.trap("INT") { server.shutdown }
port = server.listeners.first.addr[1]
puts "Webhook server listening on http://127.0.0.1:#{port}/webhook"
$stdout.flush
server.start
response_workers.each(&:join)
このような Webhook の動作を確認するには、OpenAI ダッシュボードで response.completed を購読する Webhook エンドポイントを設定し、API リクエストを送信してバックグラウンドモードでレスポンスを生成します。
Webhook 設定ページから、サンプルデータを使ったテストイベントを発生させることもできます。
1
2
3
4
5
6
7
8curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": "Write a very long novel about otters in space.",
"background": true
}'
1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const client = new OpenAI();
const resp = await client.responses.create({
model: "gpt-6-astra",
input: "Write a very long novel about otters in space.",
background: true,
});
console.log(resp.status);
1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-6-astra",
input="Write a very long novel about otters in space.",
background=True,
)
print(resp.status)
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
26package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Background: openai.Bool(true),
Input: responses.ResponseNewParamsInputUnion{
OfString: openai.String("Write a very long novel about otters in space."),
},
})
if err != nil {
panic(err)
}
fmt.Println(response.Status)
}
1
2
3
4
5
6
7
8
9
10
11
12
13import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6-astra")
.input("Write a detailed market analysis.")
.background(true)
.build();
var response = client.responses().create(params);
System.out.println(response.status().orElseThrow());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17using OpenAI.Responses;
#pragma warning disable OPENAI001
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);
CreateResponseOptions options = new()
{
Model = "gpt-6-astra",
BackgroundModeEnabled = true,
};
options.InputItems.Add(
ResponseItem.CreateUserMessageItem("Write a very long novel about otters in space.")
);
ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.Status);
1
2
3
4
5
6
7
8
9
10require "openai"
client = OpenAI::Client.new
response = client.responses.create(
model: "gpt-6-astra",
input: "Write a detailed market analysis.",
background: true
)
puts(response.status)
このガイドでは、ダッシュボードで Webhook エンドポイントを作成する方法、Webhook を処理するサーバー側のコードを設定する方法、受信したリクエストが OpenAI から送信されたことを検証する方法を説明します。
サーバーで Webhook リクエストの受信を開始するには、ダッシュボードにログインし、Webhook 設定ページを開きます。Webhook はプロジェクトごとに設定します。
「作成」ボタンをクリックして、新しい Webhook エンドポイントを作成します。設定する項目は次の 3 つです。
- エンドポイントの名前（自分で識別するためのもの）
- 管理下のサーバーの公開 URL
- 購読する 1 つ以上のイベントタイプ。これらのイベントが発生すると、OpenAI は指定された URL に HTTP POST リクエストを送信します。
新しい 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 のテストには、インターネットからアクセスできる公開 URL が必要です。通常、ローカル開発環境は公開されていないため、開発が難しくなることがあります。次のような選択肢が役立ちます。
検証を行わなくても 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
6
7
8
9
10const client = new OpenAI();
const webhook_secret = process.env.OPENAI_WEBHOOK_SECRET;
if (!webhook_secret) throw new Error("Set OPENAI_WEBHOOK_SECRET.");
// will throw if the signature is invalid
const event = await client.webhooks.unwrap(
req.body,
req.headers,
webhook_secret
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14import os
from flask import request
from openai import OpenAI
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,
)
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
26
27
28
29
30
31
32
33
34
35
36
37
38require "openai"
require "webrick"
client = OpenAI::Client.new(
api_key: ENV.fetch("OPENAI_API_KEY"),
webhook_secret: ENV.fetch("OPENAI_WEBHOOK_SECRET")
)
server = WEBrick::HTTPServer.new(
BindAddress: "127.0.0.1",
Port: Integer(ENV.fetch("OPENAI_WEBHOOK_PORT", "8000")),
Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN),
AccessLog: []
)
server.mount_proc("/webhook") do |request, response|
if request.request_method != "POST"
response.status = 405
next
end
headers = request.header.transform_values(&:first)
event = client.webhooks.unwrap(request.body, headers)
puts "Verified webhook event: #{event.type}"
response.status = 200
response.body = "ok"
rescue OpenAI::Errors::InvalidWebhookSignatureError, ArgumentError
response.status = 400
response.body = "Invalid signature"
ensure
server.shutdown if ENV["OPENAI_WEBHOOK_EXIT_AFTER_REQUEST"] == "1"
end
Signal.trap("INT") { server.shutdown }
port = server.listeners.first.addr[1]
puts "Webhook server listening on http://127.0.0.1:#{port}/webhook"
$stdout.flush
server.start
Standard Webhooks ライブラリを使って署名を検証することもできます。
1
2
3
4
5use standardwebhooks::Webhook;
let webhook_secret = std::env::var("OPENAI_WEBHOOK_SECRET").expect("OPENAI_WEBHOOK_SECRET not set");
let wh = Webhook::new(webhook_secret);
wh.verify(webhook_payload, webhook_headers).expect("Webhook verification failed");
1
2
3$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);
また、必要に応じて、Standard Webhooks 仕様の説明に従って署名検証を独自に実装することもできます。
署名シークレットを紛失したり、誤って公開したりした場合は、署名シークレットをローテーションすることで、新しいものを生成できます。
