Les webhooks OpenAI vous permettent de recevoir des notifications en temps réel sur les événements de l’API, par exemple lorsqu’un traitement par lots se termine, qu’une réponse est générée en arrière-plan ou qu’une tâche d’affinage se termine. Les webhooks sont envoyés à un point de terminaison HTTP que vous contrôlez, conformément à la spécification Standard Webhooks. La liste complète des événements webhook figure dans la Référence de l’API.
Pour recevoir des notifications de surveillance du désalignement pour un projet API, consultez Recevoir des alertes de sécurité pour un projet.
Pour les sessions de l’API Agents, consultez Webhooks de session pour en savoir plus sur les événements de session et les stratégies de reprise. Pour le récepteur de webhooks, suivez les instructions de cette page concernant la configuration du point de terminaison, la vérification des signatures et la livraison des webhooks.
Consultez la liste complète des événements webhook.
Vous trouverez ci-dessous des exemples de serveurs capables de recevoir des webhooks d’OpenAI, plus précisément pour l’événement response.completed.
Pour les exemples Ruby, installez les dépendances requises avec
gem install openai webrick, puis définissez OPENAI_API_KEY et
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)Pour voir un webhook de ce type en action, vous pouvez configurer dans le tableau de bord OpenAI un point de terminaison webhook abonné à response.completed, puis envoyer une requête API pour générer une réponse en mode en arrière-plan.
Vous pouvez aussi déclencher des événements de test avec des données d’exemple depuis la page des paramètres des webhooks.
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)Ce guide vous explique comment créer des points de terminaison webhook dans le tableau de bord, mettre en place le code côté serveur pour les gérer et vérifier que les requêtes entrantes proviennent d’OpenAI.
Création de points de terminaison webhook
Pour commencer à recevoir des requêtes webhook sur votre serveur, connectez-vous au tableau de bord et ouvrez la page des paramètres des webhooks. Les webhooks se configurent par projet.
Cliquez sur le bouton « Créer » pour créer un point de terminaison webhook. Vous devrez configurer trois éléments :
- Un nom pour le point de terminaison (uniquement pour vous aider à l’identifier).
- Une URL publique vers un serveur que vous contrôlez.
- Un ou plusieurs types d’événements auxquels vous abonner. Lorsqu’ils se produiront, OpenAI enverra une requête HTTP POST à l’URL indiquée.
Après avoir créé un webhook, vous recevrez un secret de signature permettant de vérifier côté serveur les requêtes webhook entrantes. Conservez cette valeur pour la suite, car vous ne pourrez plus la consulter.
Une fois votre point de terminaison webhook créé, configurez un point de terminaison côté serveur pour traiter les données de ces événements entrants.
Traitement des requêtes webhook sur un serveur
Lorsqu’un événement auquel vous êtes abonné se produit, une requête HTTP POST comme celle-ci est envoyée à l’URL de votre webhook :
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" }
}
Votre point de terminaison doit répondre rapidement à ces requêtes HTTP entrantes avec un code de statut de réussite (2xx) pour en confirmer la réception. Pour éviter les dépassements de délai, nous recommandons de déléguer tout traitement non trivial à un processus en arrière-plan afin que le point de terminaison puisse répondre immédiatement.
Si le point de terminaison ne renvoie pas de code de statut de réussite (2xx) ou ne répond pas en quelques secondes, la requête webhook sera renvoyée. OpenAI poursuivra les tentatives d’envoi pendant une durée maximale de 72 heures, avec un délai d’attente qui augmente de façon exponentielle entre les tentatives. Les redirections 3xx ne sont pas suivies : elles sont considérées comme des échecs et vous devez mettre à jour votre point de terminaison pour utiliser l’URL de destination finale.
Dans de rares cas, en raison de problèmes internes au système, OpenAI peut envoyer plusieurs copies du même événement webhook. Vous pouvez utiliser l’en-tête webhook-id comme clé d’idempotence pour éliminer les doublons.
Tests des webhooks en local
Pour tester les webhooks, vous avez besoin d’une URL accessible sur l’Internet public. Cela peut compliquer le développement, car votre environnement de développement local n’est probablement pas accessible au public. Voici quelques solutions utiles :
- ngrok, qui permet de rendre votre serveur localhost accessible via une URL publique
- Les environnements de développement cloud comme Replit, GitHub Codespaces, Cloudflare Workers ou v0 de Vercel.
Vérification des signatures des webhooks
Vous pouvez recevoir des événements webhook d’OpenAI et traiter les résultats sans aucune vérification. Il est toutefois recommandé de vérifier que les requêtes entrantes proviennent bien d’OpenAI, surtout si votre webhook déclenche une action côté backend. Les en-têtes des requêtes webhook contiennent des informations qui, combinées à la clé secrète du webhook, permettent de vérifier que celui-ci provient d’OpenAI.
Lorsque vous créez un point de terminaison webhook dans le tableau de bord OpenAI, vous recevez un secret de signature. Rendez-le accessible sur votre serveur sous forme de variable d’environnement :
export OPENAI_WEBHOOK_SECRET="<your secret here>"
Le moyen le plus simple de vérifier les signatures des webhooks consiste à utiliser la méthode unwrap() des utilitaires du SDK OpenAI officiel :
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,
)Vous pouvez aussi vérifier les signatures avec les bibliothèques Standard Webhooks :
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);Si nécessaire, vous pouvez également implémenter votre propre vérification des signatures selon la procédure décrite dans la spécification Standard Webhooks
Si vous perdez ou divulguez accidentellement votre secret de signature, vous pouvez en générer un nouveau en effectuant une rotation du secret de signature.