Guide complet pour comprendre et utiliser les Webhooks OpenAI

Les webhooks permettent de recevoir en temps réel des notifications envoyées par l’API d’OpenAI lorsqu’un événement spécifique survient. Cela peut concerner la fin d’un fine-tuning, la complétion d’une réponse générée en arrière-plan ou l’achèvement d’un lot de requêtes. Dans cet article, nous allons voir comment mettre en place un webhook, le configurer dans le tableau de bord OpenAI, et gérer les requêtes côté serveur.

Qu’est-ce qu’un webhook ?

Un webhook est une requête HTTP POST envoyée automatiquement par un service tiers vers une URL que vous contrôlez, dès qu’un événement défini se produit. Contrairement au polling, vous n’avez pas besoin de solliciter l’API : c’est l’API qui vous informe en temps réel.

Les cas d’usage des webhooks OpenAI

Recevoir une notification quand une réponse en arrière-plan est terminée.
Être alerté de la fin d’un entraînement personnalisé (fine-tuning).
Gérer automatiquement les batches de données une fois complétés.

Créer un webhook dans le tableau de bord OpenAI

Pour commencer à recevoir des notifications :

Connectez-vous au tableau de bord OpenAI et ouvrez la page des paramètres Webhooks.
Cliquez sur Créer puis indiquez :
- Un nom pour identifier le webhook.
- L’URL publique de votre serveur.
- Les événements auxquels vous souhaitez vous abonner (exemple : response.completed).
Une fois créé, vous recevrez un secret de signature permettant de vérifier l’authenticité des requêtes.

Exemple de payload reçu

{ "object": "event", "id": "evt_685343a1381c819085d44c354e1b330e", "type": "response.completed", "created_at": 1750287018, "data": { "id": "resp_abc123" } }

Chaque webhook inclut un identifiant unique (webhook-id) qui peut servir de clé d’idempotence pour éviter de traiter deux fois le même événement.

Mettre en place un serveur pour gérer les webhooks

Votre serveur doit pouvoir recevoir et répondre rapidement aux requêtes HTTP POST envoyées par OpenAI. Voici deux exemples simples : un en Python (Flask) et un en JavaScript (Express).

Exemple en Python

 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:
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:
return Response("Invalid signature", status=400)

if name == "main":
app.run(port=8000)

Exemple en JavaScript

 import OpenAI from "openai"; import express from "express";

const app = express();
const client = new OpenAI({ webhookSecret: process.env.OPENAI_WEBHOOK_SECRET });
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);
console.log("Response output:", response.output_text);
}
res.status(200).send();
} catch (error) {
res.status(400).send("Invalid signature");
}
});

app.listen(8000, () => console.log("Server running on port 8000"));

Tester un webhook en local

Comme votre serveur doit être accessible publiquement, il est nécessaire d’utiliser un outil de tunnelisation :

Vérifier la signature des requêtes

Pour des raisons de sécurité, il est recommandé de toujours vérifier la signature des webhooks :

 event = client.webhooks.unwrap(request.data, request.headers, secret=os.environ["OPENAI_WEBHOOK_SECRET"])

Bonnes pratiques

Répondre rapidement avec un code 2xx pour éviter les retries.
Utiliser le header webhook-id pour éviter les doublons.
Stocker le secret dans une variable d’environnement.
Externaliser le traitement lourd vers un worker en arrière-plan.

Conclusion

Les webhooks d’OpenAI sont un outil puissant pour automatiser vos processus et intégrer des réponses en temps réel dans vos applications. Bien configurés et sécurisés, ils vous permettent de gagner en efficacité et de fluidifier vos workflows avec l’API.