Mit Webhooks von OpenAI erfährst du in Echtzeit, wenn in der API ein Ereignis eintritt, etwa wenn ein Batch abgeschlossen ist, eine Antwort im Hintergrund generiert wurde oder ein Fine-Tuning-Job beendet ist. OpenAI sendet die Webhooks gemäß der Spezifikation von Standard Webhooks an einen HTTP-Endpunkt, den du kontrollierst. Die vollständige Liste der Webhook-Ereignisse findest du in der API-Referenz.
Wie du Benachrichtigungen aus der Misalignment-Überwachung für ein API-Projekt erhältst, erfährst du im Abschnitt Sicherheitswarnungen für ein Projekt empfangen.
Wie du auf Organisationsebene Warnungen und Deaktivierungsmitteilungen zu Sicherheitskennungen erhältst, erfährst du im Leitfaden Benachrichtigungen zur Durchsetzung von Sicherheitsrichtlinien.
Für Sitzungen der Agents API findest du im Leitfaden Webhooks für Sitzungen Informationen zu Sitzungsereignissen und Verfahren zur Wiederherstellung. Wenn du den Webhook-Empfänger implementierst, beachte die Hinweise auf dieser Seite zum Einrichten des Endpunkts, zur Signaturprüfung und zur Zustellung.
Sieh dir die vollständige Liste der Webhook-Ereignisse an.
Die folgenden Beispiele zeigen, wie ein Server Webhooks von OpenAI für das Ereignis response.completed empfängt.
Installiere für die Ruby-Beispiele die erforderlichen Abhängigkeiten mit
gem install openai webrick und setze anschließend die Umgebungsvariablen OPENAI_API_KEY und
OPENAI_WEBHOOK_SECRET.
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)Um einen solchen Webhook auszuprobieren, richte im OpenAI-Dashboard einen Webhook-Endpunkt ein, der das Ereignis response.completed abonniert. Sende dann eine API-Anfrage, um eine Antwort im Hintergrundmodus zu generieren.
In den Webhook-Einstellungen kannst du auch Testereignisse mit Beispieldaten auslösen.
from 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)In diesem Leitfaden erfährst du, wie du Webhook-Endpunkte im Dashboard erstellst, auf deinem Server Code zur Verarbeitung eingehender Anfragen einrichtest und prüfst, ob die Anfragen von OpenAI stammen.
Webhook-Endpunkte erstellen
Um Webhook-Anfragen für dein Projekt auf deinem Server zu empfangen, melde dich im Dashboard an und öffne die Webhook-Einstellungen. Die folgenden Schritte gelten für Projektendpunkte. Informationen zu Sicherheitsereignissen auf Organisationsebene findest du im Leitfaden Benachrichtigungen zur Durchsetzung von Sicherheitsrichtlinien.
Klicke auf „Erstellen“, um einen neuen Webhook-Endpunkt anzulegen. Gib die folgenden drei Angaben ein.
- Einen Namen für den Endpunkt, damit du ihn später wiedererkennst.
- Eine öffentliche URL auf einem Server, den du kontrollierst.
- Einen oder mehrere Ereignistypen, die du abonnieren möchtest. Tritt ein solches Ereignis ein, sendet OpenAI eine HTTP-POST-Anfrage an die angegebene URL.
Nachdem du einen neuen Webhook erstellt hast, erhältst du einen geheimen Signaturschlüssel. Damit prüfst du eingehende Webhook-Anfragen auf deinem Server. Speichere den Schlüssel für später, denn du kannst ihn dir nur einmal anzeigen lassen.
Richte als Nächstes den Endpunkt auf deinem Server so ein, dass er die eingehenden Ereignisdaten verarbeitet.
Webhook-Anfragen auf dem Server verarbeiten
Wenn ein abonniertes Ereignis eintritt, geht an deiner Webhook-URL eine HTTP-POST-Anfrage wie diese ein.
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" }
}
Dein Endpunkt sollte den Empfang dieser HTTP-Anfragen umgehend mit einem Erfolgsstatuscode (2xx) bestätigen. Um Zeitüberschreitungen zu vermeiden, empfehlen wir, aufwendigere Verarbeitungsschritte an einen Hintergrundprozess zu übergeben. So kann der Endpunkt sofort antworten.
Gibt der Endpunkt keinen Erfolgsstatuscode (2xx) zurück oder antwortet er nicht innerhalb weniger Sekunden, sendet OpenAI die Webhook-Anfrage erneut. OpenAI wiederholt die Zustellversuche bis zu 72 Stunden lang mit exponentiell wachsenden Wartezeiten. Weiterleitungen mit 3xx gelten als fehlgeschlagene Zustellversuche. OpenAI folgt ihnen nicht. Aktualisiere in diesem Fall deinen Endpunkt so, dass er direkt die endgültige Ziel-URL verwendet.
In seltenen Fällen kann OpenAI dasselbe Webhook-Ereignis aufgrund interner Systemprobleme mehrfach zustellen. Du kannst den Header webhook-id als Idempotenzschlüssel verwenden, um Duplikate zu erkennen und das Ereignis nur einmal zu verarbeiten.
Webhooks lokal testen
Zum Testen von Webhooks brauchst du eine URL, die über das öffentliche Internet erreichbar ist. Das kann die Entwicklung erschweren, da deine lokale Entwicklungsumgebung wahrscheinlich nicht öffentlich zugänglich ist. Dafür kommen unter anderem die folgenden Optionen infrage.
- Mit ngrok kannst du deinen localhost-Server über eine öffentliche URL zugänglich machen.
- Du kannst eine Cloud-Entwicklungsumgebung wie Replit, GitHub Codespaces, Cloudflare Workers oder v0 von Vercel verwenden.
Webhook-Signaturen prüfen
Du kannst Webhook-Ereignisse von OpenAI ohne Prüfung empfangen und die Ergebnisse verarbeiten. Du solltest jedoch prüfen, ob eingehende Anfragen tatsächlich von OpenAI stammen, besonders wenn dein Webhook Aktionen im Backend auslöst. Die Header jeder Webhook-Anfrage enthalten die Angaben, die du zusammen mit dem geheimen Signaturschlüssel brauchst, um die Herkunft der Anfrage zu prüfen.
Wenn du im OpenAI-Dashboard einen Webhook-Endpunkt erstellst, erhältst du einen geheimen Signaturschlüssel. Stelle ihn auf deinem Server als Umgebungsvariable bereit.
export OPENAI_WEBHOOK_SECRET="<your secret here>"
Am einfachsten prüfst du Webhook-Signaturen mit der Hilfsmethode unwrap() aus den offiziellen OpenAI SDKs.
import 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,
)Du kannst die Signaturen auch mit den Bibliotheken von Standard Webhooks prüfen.
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);Bei Bedarf kannst du die Signaturprüfung auch selbst implementieren, wie in der Spezifikation von Standard Webhooks beschrieben.
Wenn du deinen geheimen Signaturschlüssel verlierst oder versehentlich offenlegst, kannst du einen neuen generieren, indem du den Signaturschlüssel rotierst.