Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Webhooks

Mit Webhooks erhältst du Benachrichtigungen von der OpenAI API in Echtzeit.

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.

API-Referenz für Webhook-Ereignisse

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.

Webhook-Server
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.

Eine Antwort im Hintergrund generieren
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.
Dialog zum Bearbeiten eines Webhook-Endpunkts

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.

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.

Signaturen mit dem OpenAI SDK prüfen
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.

Signaturen 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.