---
title: "Guide complet pour comprendre et utiliser les Webhooks OpenAI"
description: "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…"
url: "https://eclaircms.ludicweb.fr/blog/guide-complet-pour-comprendre-et-utiliser-les-webhooks-openai"
lang: "fr"
author: "Christophe Marcellin"
published: "2025-10-17"
updated: "2026-11-04"
---

# 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 :

1. Connectez-vous au tableau de bord OpenAI et ouvrez la page des [paramètres Webhooks](https://eclaircms.ludicweb.fr/settings/project/webhooks).
2. Cliquez sur *Créer* puis indiquez : wp:list 

Un **nom** pour identifier le webhook.


L’**URL publique** de votre serveur.


Les **événements** auxquels vous souhaitez vous abonner (exemple : `response.completed`).

 /wp:list
3. 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 :

- [ngrok](https://ngrok.com/)
- [Replit](https://replit.com/)
- [GitHub Codespaces](https://github.com/features/codespaces)
- [Vercel v0](https://v0.dev/)

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

— Christophe Marcellin, Éditeur web indépendant | High-Tech, IA, SEO et tutoriels · 4 novembre 2026