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 ダッシュボードで Webhook エンドポイントを設定し、response.completed を購読します。次に、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 エンドポイントを作成し、リクエストを処理するコードをサーバー側に実装して、受信したリクエストの送信元が OpenAI であることを検証する方法を説明します。
プロジェクトの 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）を返さなかった場合や、数秒以内に応答しなかった場合、OpenAI は Webhook リクエストを再送します。再送間隔は指数バックオフで徐々に延び、再送は最長 72 時間続きます。3xx リダイレクトは失敗として扱われ、リダイレクト先への送信は行われません。エンドポイントには最終的な宛先の URL を設定してください。
まれに、OpenAI の内部システムの問題で、同じ Webhook イベントが複数回配信されることがあります。webhook-id ヘッダーを冪等性キーとして使うと、同じイベントを重複して処理せずに済みます。
Webhook のテストには、インターネットからアクセスできる公開 URL が必要です。ローカル開発環境は通常、外部に公開されていないため、そのままではテストが難しい場合があります。次のようなツールや環境を利用できます。
署名を検証しなくても OpenAI からの Webhook イベントを受信して結果を処理できますが、受信したリクエストの送信元が OpenAI であることを検証してください。特に、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// Verify the original bytes, before any JSON parsing.
event, err := client.Webhooks.Unwrap(body, r.Header)
if err != nil {
http.Error(w, "Invalid webhook", http.StatusBadRequest)
return
}
fmt.Println(event.Type)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.OpenAIClient;
import com.openai.core.http.Headers;
import com.openai.models.webhooks.UnwrapWebhookEvent;
import com.openai.models.webhooks.WebhookVerificationParams;
// Your HTTP framework supplies the original request bytes and headers.
// Load secret from OPENAI_WEBHOOK_SECRET in your application.
// Reject InvalidWebhookSignatureException (invalid signature or timestamp)
// and IllegalArgumentException (missing required headers).
public static UnwrapWebhookEvent verifyWebhook(
OpenAIClient client, byte[] body, Headers headers, String secret) {
return client
.webhooks()
.unwrap(
WebhookVerificationParams.builder()
.payload(body)
.headers(headers)
.secret(secret)
.build());
}
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 仕様に記載された手順に従って署名検証を独自に実装することもできます。
署名シークレットを紛失した場合や誤って公開した場合は、署名シークレットをローテーションして新しいシークレットを発行できます。
