OpenAI 웹훅을 사용하면 배치가 완료되거나 백그라운드 응답이 생성되거나 파인튜닝 작업이 끝나는 등 API에서 이벤트가 발생할 때 실시간으로 알림을 받을 수 있습니다. OpenAI는 Standard Webhooks 사양에 따라 사용자가 관리하는 HTTP 엔드포인트로 웹훅을 전송합니다. 웹훅 이벤트의 전체 목록은 API 레퍼런스에서 확인할 수 있습니다.
API 프로젝트의 정렬 이탈 모니터링 알림을 받으려면 프로젝트 안전 알림 받기를 참고하세요.
안전 식별자에 대한 경고 및 비활성화 알림을 조직 수준에서 받으려면 안전 정책 집행 알림을 참고하세요.
Agents API 세션의 이벤트와 복구 패턴은 세션 웹훅을 참고하세요. 웹훅을 수신하는 서버를 구성할 때는 이 페이지의 엔드포인트 설정, 서명 검증, 전송 관련 안내를 따르세요.
다음은 OpenAI 웹훅을 수신하는 서버 예제입니다. 여기서는 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)
웹훅이 어떻게 동작하는지 확인하려면 OpenAI 대시보드에서 웹훅 엔드포인트를 설정하고 response.completed 이벤트를 구독하세요. 그런 다음 API 요청을 보내 백그라운드 모드에서 응답을 생성하세요.
웹훅 설정 페이지에서 샘플 데이터로 테스트 이벤트를 발생시킬 수도 있습니다.
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)
이 가이드에서는 대시보드에서 웹훅 엔드포인트를 만들고, 서버에서 웹훅 요청을 처리하는 코드를 설정하고, 수신한 요청을 OpenAI가 보냈는지 검증하는 방법을 알아봅니다.
서버에서 프로젝트 웹훅 요청을 받으려면 대시보드에 로그인하고 웹훅 설정 페이지를 여세요. 이 섹션에서는 프로젝트 엔드포인트를 설정합니다. 조직 수준의 안전 이벤트는 안전 정책 집행 알림을 참고하세요.
“만들기” 버튼을 클릭해 새 웹훅 엔드포인트를 만드세요. 다음 세 가지 항목을 설정합니다.
- 엔드포인트 이름. 나중에 엔드포인트를 알아볼 수 있는 이름을 지정하세요.
- 직접 관리하는 서버의 공개 URL.
- 구독할 이벤트 유형 한 개 이상. 해당 이벤트가 발생하면 OpenAI가 지정한 URL로 HTTP POST 요청을 보냅니다.
새 웹훅을 만들면 서버에서 수신한 웹훅 요청을 검증하는 데 필요한 서명용 비밀 키가 발급됩니다. 이 값은 다시 확인할 수 없으므로 나중에 사용할 수 있도록 저장하세요.
웹훅 엔드포인트를 만들었다면 이제 수신한 이벤트 페이로드를 처리할 서버 측 엔드포인트를 설정하세요.
구독한 이벤트가 발생하면 웹훅 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가 웹훅 요청을 다시 보냅니다. 재시도 간격은 지수 백오프 방식으로 늘어나며, 전송 시도는 최대 72시간 동안 계속됩니다. OpenAI는 3xx 리디렉션을 따라가지 않고 전송 실패로 처리하므로 엔드포인트에 최종 목적지 URL을 지정하세요.
드물게 OpenAI 내부 시스템 문제로 동일한 웹훅 이벤트가 여러 번 전송될 수 있습니다. webhook-id 헤더를 멱등성 키로 사용하면 중복 이벤트를 걸러낼 수 있습니다.
웹훅을 테스트하려면 인터넷에서 접근할 수 있는 공개 URL이 필요합니다. 로컬 개발 환경은 대개 외부에 공개되어 있지 않아 웹훅을 테스트하기 어렵습니다. 이때 다음 도구를 활용할 수 있습니다.
OpenAI 웹훅 이벤트를 검증 없이 수신하고 처리할 수는 있지만, 수신한 요청을 실제로 OpenAI가 보냈는지 검증해야 합니다. 특히 웹훅을 수신한 후 백엔드에서 작업을 수행한다면 검증이 중요합니다. 웹훅 요청에 포함된 헤더 정보와 웹훅 비밀 키를 함께 사용하면 OpenAI가 보낸 웹훅인지 검증할 수 있습니다.
OpenAI 대시보드에서 웹훅 엔드포인트를 만들면 서명용 비밀 키가 발급됩니다. 서버에서 이 키를 사용할 수 있도록 환경 변수로 설정하세요.
export OPENAI_WEBHOOK_SECRET="<your secret here>"
웹훅 서명을 검증하는 가장 간단한 방법은 공식 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 사양의 검증 절차에 따라 서명 검증을 직접 구현할 수도 있습니다.
서명용 비밀 키를 분실했거나 실수로 노출했다면 서명용 비밀 키 교체를 통해 새 키를 발급받을 수 있습니다.
