For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Hauptnavigation

Webhooks

Empfange mit Webhooks Echtzeit-Updates von der OpenAI API.

Mit Webhooks von OpenAI erhältst du Echtzeit-Benachrichtigungen über Ereignisse in der API, etwa wenn eine Stapelverarbeitung abgeschlossen, eine Antwort im Hintergrund generiert oder ein Fine-Tuning-Job beendet wird. Webhooks werden gemäß der Spezifikation von Standard Webhooks an einen HTTP-Endpunkt gesendet, den du kontrollierst. Die vollständige Liste der Webhook-Ereignisse findest du in der API-Referenz.

Wie du für ein API-Projekt Benachrichtigungen zur Überwachung auf Alignment-Abweichungen erhältst, erfährst du unter Sicherheitswarnungen für Projekte empfangen.

Informationen zu Sitzungsereignissen und Wiederherstellungsmustern für Sitzungen der Agents API findest du unter Webhooks für Sitzungen. Beachte für den Webhook-Empfänger 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.

Nachfolgend findest du Beispiele für Server, die Webhooks von OpenAI empfangen können, speziell für das Ereignis response.completed.

Installiere für die Ruby-Beispiele die erforderlichen Abhängigkeiten mit gem install openai webrick und setze anschließend 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, kannst du im OpenAI-Dashboard einen Webhook-Endpunkt einrichten, der response.completed abonniert. Sende dann eine API-Anfrage, um eine Antwort im Hintergrundmodus zu generieren.

Du kannst auch auf der Seite mit den Webhook-Einstellungen 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 dieser Anleitung erfährst du, wie du Webhook-Endpunkte im Dashboard erstellst, serverseitigen Code für ihre Verarbeitung einrichtest und überprüfst, ob eingehende Anfragen von OpenAI stammen.

Webhook-Endpunkte erstellen

Um Webhook-Anfragen auf deinem Server zu empfangen, melde dich im Dashboard an und öffne die Seite mit den Webhook-Einstellungen. Webhooks werden für jedes Projekt separat konfiguriert.

Klicke auf „Erstellen“, um einen neuen Webhook-Endpunkt zu erstellen. Dabei legst du drei Dinge fest:

  • Einen Namen für den Endpunkt (nur zu deiner Orientierung).
  • Eine öffentliche URL zu einem Server, den du kontrollierst.
  • Einen oder mehrere Ereignistypen, die du abonnieren möchtest. Wenn diese Ereignisse eintreten, 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, mit dem du eingehende Webhook-Anfragen serverseitig überprüfen kannst. Speichere diesen Wert für später, da du ihn nicht erneut anzeigen kannst.

Nachdem du deinen Webhook-Endpunkt erstellt hast, richtest du als Nächstes einen serverseitigen Endpunkt ein, der die eingehenden Ereignisdaten verarbeitet.

Webhook-Anfragen auf einem Server verarbeiten

Wenn ein Ereignis eintritt, das du abonniert hast, erhält deine Webhook-URL eine HTTP-POST-Anfrage wie diese:

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 auf diese eingehenden HTTP-Anfragen schnell mit einem Erfolgsstatuscode (2xx) antworten, um den Empfang zu bestätigen. Um Zeitüberschreitungen zu vermeiden, empfehlen wir, aufwendigere Verarbeitungsschritte an einen Hintergrund-Worker auszulagern, damit der Endpunkt sofort antworten kann. Wenn der Endpunkt keinen Erfolgsstatuscode (2xx) zurückgibt oder nicht innerhalb weniger Sekunden antwortet, wird die Webhook-Anfrage erneut gesendet. OpenAI versucht die Zustellung bis zu 72 Stunden lang mit exponentiell zunehmenden Wartezeiten zwischen den Versuchen. Beachte, dass 3xx-Weiterleitungen nicht gefolgt wird. Sie gelten als Fehler. Aktualisiere deinen Endpunkt daher so, dass er die endgültige Ziel-URL verwendet.

In seltenen Fällen kann OpenAI aufgrund interner Systemprobleme dasselbe Webhook-Ereignis mehrfach zustellen. Du kannst den Header webhook-id als Idempotenzschlüssel verwenden, um Duplikate herauszufiltern.

Webhooks lokal testen

Zum Testen von Webhooks benötigst 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. Hier sind einige Möglichkeiten, die dir helfen können:

Webhook-Signaturen überprüfen

Du kannst Webhook-Ereignisse von OpenAI ohne Überprüfung empfangen und die Ergebnisse verarbeiten. Dennoch solltest du überprüfen, ob eingehende Anfragen tatsächlich von OpenAI stammen, insbesondere wenn dein Webhook Aktionen im Backend auslöst. Die mit Webhook-Anfragen gesendeten Header enthalten Informationen, mit denen du zusammen mit einem geheimen Webhook-Schlüssel überprüfen kannst, ob der Webhook von OpenAI stammt.

Wenn du im OpenAI-Dashboard einen Webhook-Endpunkt erstellst, erhältst du einen geheimen Signaturschlüssel. Diesen solltest du auf deinem Server als Umgebungsvariable bereitstellen:

export OPENAI_WEBHOOK_SECRET="<your secret here>"

Am einfachsten überprüfst du Webhook-Signaturen mit der Methode unwrap() aus den Hilfsfunktionen des offiziellen OpenAI SDK:

Signaturprüfung mit dem OpenAI SDK
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,
)

Signaturen lassen sich auch mit den Bibliotheken von Standard Webhooks überprüfen:

Signaturprüfung mit den Bibliotheken von Standard Webhooks
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);

Bei Bedarf kannst du alternativ eine eigene Signaturprüfung implementieren, wie in der Spezifikation von Standard Webhooks beschrieben

Wenn du deinen geheimen Signaturschlüssel verlierst oder versehentlich offenlegst, kannst du durch Rotation des Signaturschlüssels einen neuen generieren.