Webhooks IA asynchrones sur Localhost : OpenAI Batch et les deux modèles de webhook de Gemini
Déboguez les webhooks OpenAI Batch et Gemini sur localhost sans relancer les travaux. Découvrez les modèles de webhook statique et dynamique de Gemini, HMAC, JWKS et les payloads Batch.

Quick answer
Webhooks IA asynchrones sur Localhost : OpenAI Batch et Gemini (2026): webhook testing answer
For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.
How do I test webhooks on localhost?
Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.
Why does a stable webhook URL matter?
Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.
Les travaux par batch sont coûteux à déboguer. Vous soumettez des milliers de prompts, vous attendez des heures, et votre gestionnaire de callback ne voit l’entrée réelle que lorsque le travail est terminé. Si le gestionnaire a un bug, la solution rapide est de relancer le batch.
Vous ne devriez pas avoir à le faire. OpenAI et Google envoient désormais des événements de complétion au lieu de vous faire interroger. Google a annoncé des webhooks pilotés par les événements pour l’API Gemini le 4 mai 2026. OpenAI livre des callbacks qui suivent la spécification Standard Webhooks pour les batches, les réponses en arrière-plan, les travaux de fine-tuning et d’autres événements. Ce guide porte sur le cycle de vie du travail. Il explique comment recevoir ces callbacks sur Localhost, comment les deux modèles de configuration de Gemini diffèrent, et pourquoi un événement de réussite de batch donne une référence au lieu des résultats. Il montre aussi comment itérer sur votre gestionnaire sans payer pour un autre batch.
(Les échecs de signature derrière un tunnel, tels que des corps ré-serialisés, constituent un sujet distinct et ne sont pas approfondis ici.)
Pourquoi les travaux d’IA de longue durée ont besoin de webhooks
Le polling fonctionne, mais il génère des appels superflus et ajoute de la latence. Sur OpenAI, vous interrogez GET /v1/batches/{batch_id}. Du côté Gemini, le post de lancement de Google décrit appeler à plusieurs reprises GET sur les opérations. Google présente le problème comme un travail à forte activité et axé sur l’agent, comme Deep Research, la génération vidéo longue, ou des milliers de prompts via l’API Batch, où les opérations peuvent prendre des minutes, voire des heures.
La fenêtre de complétion est le chiffre clé. L’API Batch d’OpenAI n’accepte actuellement qu’une fenêtre de complétion de 24h, et sa documentation promet que chaque batch se termine en 24 heures, souvent plus tôt. Le catalogue d’événements de Gemini décrit batch.expired comme un batch qui n’a pas été terminé dans un délai de 24 heures. Un callback peut donc arriver à n’importe quel moment pendant cette journée. C’est le moment où votre ordinateur portable est le plus susceptible d’avoir changé de réseau, redémarré ou été mis en veille.
Deux précisions avant de vous lancer :
- La documentation des webhooks de Gemini qualifier la fonctionnalité de préversion, même si le post de lancement de Google indique qu’elle est disponible pour tous les développeurs de Gemini API. Attendez-vous à des changements et revérifiez la documentation avant de déployer.
- L’API Batch d’OpenAI offre une réduction de coût de 50 % par rapport aux API synchrones. Cette réduction est aussi la raison pour laquelle relancer un batch échoué à cause d’un bug du gestionnaire est une habitude si tentante et gaspilleuse.
Aperçu des webhooks OpenAI et Gemini
| OpenAI | Gemini API | |
|---|---|---|
| Où sont configurés | Par projet : tableau de bord (nom, URL publique, types d’événements) ou l’API Webhooks | Statique : API WebhookService. Dynamique : webhook_config sur une requête |
| Événements de batch | batch.completed, batch.failed, batch.cancelled, batch.expired |
batch.succeeded, batch.failed, batch.cancelled, batch.expired |
| Autres événements asynchrones | response.completed/failed/cancelled/incomplete, fine_tuning.job.succeeded/failed/cancelled, eval.run.succeeded/failed/canceled, realtime.call.incoming |
interaction.requires_action/completed/failed/cancelled, video.generated |
| Signature | En-têtes Webhooks Standards (webhook-id, webhook-timestamp, webhook-signature); secret affiché une fois à la création |
Statique : HMAC Webhooks Standard, secret affiché une fois. Dynamique : JWT RS256 dans l’en-tête Webhook-Signature, vérifié contre un JWKS |
| Payload | Fin : object, id d’événement, type, created_at, data.id |
Fin : type, version, timestamp, data |
| Réessais | Réessayé si non-2xx ou pas de réponse en quelques secondes jusqu’à 72 heures avec backoff exponentiel; les redirections 3xx ne sont pas suivies | Réessayé pendant 24 heures avec backoff exponentiel ; répondre 2xx en quelques secondes |
| Maturité | Guide documenté et référence API | Marqué comme préversion dans la doc |
Trois détails comptent tout de suite.
- L’événement de réussite porte un nom différent. Il est
batch.completedsur OpenAI etbatch.succeededsur Gemini. Un gestionnaire commun indexé sur la chaînetypenécessite une correspondance explicite. - Les deux fournisseurs livrent au moins une fois, donc des doublons peuvent se produire. Utilisez l’en-tête
webhook-idcomme clé d’idempotence. La documentation d’OpenAI le recommande explicitement. L’exemple de payload documenté de Gemini n’inclut pas d’ID d’événement dans le corps, l’en-tête est donc le seul choix fiable. - Un batch OpenAI « completed » ne garantit pas que chaque requête a réussi. L’objet batch suit
request_counts(total, completed, failed) et sépareoutput_file_iddeerror_file_id. Un batch terminé peut encore contenir des lignes échouées.
Les deux modèles de webhook de Gemini : statique et dynamique
C’est la partie qui différencie vraiment d’OpenAI, et la raison pour laquelle les handlers Gemini sont plus difficiles à tester.
Webhooks statiques : enregistrer une fois, tout recevoir
Les webhooks statiques sont des points de terminaison au niveau projet créés via l’API WebhookService. Ils se déclenchent pour tout événement correspondant dans le projet. En plus de les créer, vous pouvez les récupérer, les lister, les mettre à jour et les supprimer, et faire tourner leur secret de signature.
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
webhook = client.webhooks.create(
name="MyBatchWebhook",
subscribed_events=["batch.succeeded", "batch.failed"],
uri="https://my-api.com/gemini-callback",
)
# Le secret de signature n’est montré qu’une seule fois. Conservez-le en sécurité.
webhook_secret = webhook.new_signing_secret
Les webhooks statiques sont signés avec HMAC selon le schéma Standard Webhooks. Le secret de signature n’est montré qu’à la création, et si vous le perdez vous le faites tourner plutôt que de le récupérer. Rotation permet de choisir si les secrets précédents sont révoqués immédiatement ou après une période de grâce de 24 heures (revocation_behavior="revoke_previous_secrets_after_h24" dans le SDK Python). La période de grâce permet à l’ancien secret de continuer à fonctionner pendant que vous déployez le nouveau.
Astuce du développement local : un webhook statique couvre tout le projet. Un point de terminaison de développement enregistré dans le même projet Google Cloud que la production recevra les événements de production, et la production recevra les vôtres. Utilisez un projet séparé et une clé API séparée pour le développement. OpenAI a la même configuration : ses endpoints webhook sont configurés par projet, donc utilisez également un projet distinct pour le dev.
Webhooks dynamiques : sur-réglages par travail
Les webhooks dynamiques sont des surcharges au niveau de la requête. Vous passez un webhook_config dans l’appel qui crée le travail. Le post de lancement de Google montre cela pour un batch :
from google import genai
client = genai.Client()
file_batch_job = client.batches.create(
model="<your-model>",
src=inline_requests,
config={
"display_name": "My Setup",
"webhook_config": {
"uris": ["https://my-api.com/gemini-webhook-dynamic"],
"user_metadata": {"job_group": "nightly-eval", "priority": "high"},
},
},
)
Quatre détails valent la peine d’être connus :
urisest une liste, etuser_metadataest un objet clé-valeur arbitraire que vous joignez au travail. L’exemple de payload mince documenté ne montre pas queuser_metadatarevient dans la livraison. Avant de vous baser dessus, vérifiez une livraison réelle capturée pour voir si elle apparaît et où.- Pour l’API Interactions,
background=Trueest requis chaque fois quewebhook_configest défini. Les exemples d’Interactions de Google indiquent aussi qu’ils ne fonctionnent qu’avec des versions de SDK plus récentes que 2.0.0. - Les webhooks dynamiques utilisent des signatures asymétriques. Votre écouteur lit un JWT Depuis l’en-tête
Webhook-Signatureet le vérifie contre les clés publiques de Google (RS256). - Les docs de Google manquent de cohérence sur l’emplacement de ces clés. Le paragraphe référence
https://www.googleapis.com/oauth2/v3/certs, tandis que le code d’exemple récupèrehttps://generativelanguage.googleapis.com/.well-known/jwks.json. Les exemples passent aussi une valeuraudiencefictive, avec un commentaire indiquant quelque chose comme l’identifiant client de votre projet. Confirmez l’URL exacte des clés et l’audience dans la documentation actuelle avant d’appliquer l’un ou l’autre.
Un gestionnaire qui prend en charge les deux modèles nécessite donc deux chemins de vérification, car une bibliothèque Standard Webhooks ne vérifie pas le JWT dynamique. Les exemples de Google récupèrent l’ensemble des clés à chaque requête. En production, vous devriez le mettre en cache et le récupérer à nouveau lorsque vous voyez un kid inconnu.
Lequel devriez-vous utiliser ?
Utilisez statique pour les choses qui doivent toujours se produire : journalisation d’audit, notification Slack, ou un travail de synchronisation de données. Utilisez dynamique lorsque vous souhaitez router des travaux spécifiques vers des lieux différents, comme une file d’attente de workers par locataire, ou le batch d’un développeur qui atterrit sur sa machine sans toucher à la configuration du projet partagée. Pour le débogage local, le mode dynamique est souvent le choix le plus sûr. La cible du callback vit dans le travail, et non dans l’état du projet que vos coéquipiers partagent.
La charge utile de réussite du batch est une référence, et non le résultat
Aucun des deux ne vous envoie le résultat. Gemini envoie une référence (comme output_file_uri dans l’exemple de Google), et OpenAI n’envoie que l’ID du batch, après quoi vous récupérez le fichier de sortie.
L’exemple de Google utilise une URI de type gs:// Cloud Storage, qui n’est pas une URL HTTPS que vous pouvez récupérer avec un simple GET. La documentation ne précise pas comment votre gestionnaire doit le télécharger, alors ne faites pas d’hypothèses. Capturez une livraison réelle et voyez ce que vos jobs renvoient réellement. Les propres exemples de Google vérifient aussi si output_file_uri est présent avant de l’utiliser, avec un commentaire l’associant à des jobs batch créés à partir d’un fichier d’entrée. N’imaginez pas que ce champ existe sur chaque événement batch.succeeded.
Les autres événements batch de Gemini portent des données différentes. batch.failed inclut error_code et error_message, tandis que batch.cancelled et batch.expired ne portent que l’id.
Le modèle d’OpenAI est similaire. L’objet data ne contient que l’ID du batch :
{
"id": "evt_abc123",
"type": "batch.completed",
"created_at": 1719168000,
"data": { "id": "batch_abc123" }
}
Pour obtenir les résultats, vous appelez l’API Batch, lisez output_file_id à partir de l’objet batch et téléchargez-le via l’API Files. Lisez error_file_id pour les requêtes échouées. Quatre détails comptent ici :
- Les lignes de sortie peuvent ne pas correspondre à l’ordre des entrées, mappez les résultats en retour avec le
custom_idde chaque ligne. - Si un batch expire, les réponses des requêtes terminées restent disponibles dans le fichier de sortie. Les requêtes inachevées se trouvent dans le fichier d’erreurs avec une erreur
batch_expired, et vous êtes facturé pour les éléments terminés. Un gestionnaire pourbatch.expireddoit donc encore rechercher la sortie. - Annuler un batch le déplace d’abord en état
cancelling, ce qui peut prendre jusqu’à 10 minutes pendant que les requêtes en cours se terminent. Un événementbatch.cancelledn’est pas instantané. - Par défaut, les fichiers de sortie et d’erreurs des batches expirent 30 jours après leur création. Vous pouvez modifier cela avec
output_expires_after(1 heure à 30 jours) lors de la création du batch.
Ainsi, le webhook est une notification, et le travail réel se fait en une seconde étape. Cette séparation est la clé pour un débogage peu coûteux, car vous pouvez tester les deux moitiés séparément.
Déboguez le callback sans relancer le batch
Voici un flux de travail qui évite de payer un second batch.
1. Capturez une livraison réelle. Soumettez un petit batch, puis enregistrez exactement ce qui arrive : en-têtes et corps brut. Un petit enregistreur Express le fait :
import express from "express";
import fs from "node:fs";
const app = express();
fs.mkdirSync("fixtures", { recursive: true });
// Conservez le corps brut : la vérification de signature a besoin des octets exacts
app.use(express.text({ type: "application/json" }));
app.post("/hooks/:provider", (req, res) => {
fs.writeFileSync(
`fixtures/${req.params.provider}-${Date.now()}.json`,
JSON.stringify({ headers: req.headers, body: req.body }, null, 2)
);
res.sendStatus(200);
});
app.listen(3000);
Répondez rapidement par 2xx. Les deux fournisseurs réessaieront si vous ne répondez pas en quelques secondes, alors enregistrez d’abord et traitez plus tard. Les fixtures contiennent des IDs de travail et éventuellement des emplacements de sortie, il faut donc les exclure du contrôle de version.
2. Séparez vérification et traitement. Structurez votre code comme verify(request) -> event suivi de handle(event). Vous pouvez ensuite envoyer des événements sauvegardés directement à handle() et ignorer les vérifications de signature. Les helpers de vérification existent déjà. Les SDKs d’OpenAI fournissent client.webhooks.unwrap(body, headers). Pour les webhooks statiques Gemini, les exemples de Google utilisent la bibliothèque standardwebhooks. Pour les dynamiques, vous vérifiez vous-même le JWT.
Cette séparation est particulièrement utile pour les webhooks dynamiques de Gemini. Vous ne pouvez pas ré-signer une livraison enregistrée, car vous ne détenez pas la clé privée de Google. Un jeton enregistré peut cesser de vérifier, par exemple s’il expire ou si Google fait tourner les clés, et la documentation n’indique pas la durée de validité des jetons. Réjouer l’événement analysé dans handle() évite entièrement ce problème.
3. Normalisez les noms d’événements à la frontière. Mappez les chaînes type de chaque fournisseur vers un seul vocabulaire interne avant que votre logique métier ne les voie :
TERMINAL_STATUS = {
("openai", "batch.completed"): "succeeded",
("openai", "batch.failed"): "failed",
("openai", "batch.cancelled"): "cancelled",
("openai", "batch.expired"): "expired",
("gemini", "batch.succeeded"): "succeeded",
("gemini", "batch.failed"): "failed",
("gemini", "batch.cancelled"): "cancelled",
("gemini", "batch.expired"): "expired",
}
4. Faites attention à la fenêtre de fraîcheur. Les meilleures pratiques de Google indiquent de rejeter les payloads dont le webhook-timestamp est plus ancien que cinq minutes, afin d’atténuer les attaques par relecture. Un fixture sauvegardé réutilisé une heure plus tard devrait échouer avec un gestionnaire correct. Pour les signatures des webhooks statiques Gemini et OpenAI, ré-signaturez les fixtures avec une clé de test et un horodatage frais, ou rendez la tolérance configurable uniquement en développement.
5. Simuler la récupération du pointeur. Placez un petit fichier de sortie sur disque et remplacez votre API Files ou lecteur de stockage par une version locale. La réussite devient ainsi un test rapide hors ligne qui ne nécessite pas d’identifiants cloud.
6. Testez les chemins difficiles. Enregistrez des fixtures pour batch.failed, batch.expired et batch.cancelled également, car vous ne les voyez presque jamais en trafic réel. Incluez un batch OpenAI avec un error_file_id non vide. Écrivez aussi à la main une livraison en double avec le même webhook-id pour confirmer que votre vérification d’idempotence fonctionne.
7. Utilisez les outils de test fournis par les fournisseurs lorsque disponibles. La page des paramètres des webhooks du tableau de bord OpenAI peut déclencher des événements de test avec des données d’exemple, et sa référence API indique une méthode “Test Webhook Endpoint”. La documentation des webhooks Gemini ne décrit pas d’équivalent, vos fixtures enregistrées accomplissent donc ce travail.
8. Accordez les données avec une seule utilisation du polling. Les réessais sont limités : 24 heures sur Gemini, jusqu’à 72 heures pour OpenAI. Si votre point de terminaison est indisponible plus longtemps, l’événement est perdu, et un batch peut lui-même prendre jusqu’à 24 heures. Au démarrage, parcourez votre grand livre des travaux pour repérer les travaux marqués submitted et vérifiez leur statut avec un seul GET. Considérez les webhooks comme la voie rapide et le polling comme un filet de sécurité. Faites-le avant l’expiration des fichiers de sortie, 30 jours par défaut sur OpenAI.
Votre grand livre peut être simple : identifiant du travail, fournisseur, statut (submitted, succeeded, failed, cancelled, expired) et le dernier webhook-id traité. Aucune documentation des deux fournisseurs ne garantit l’ordre de livraison, appliquez les mises à jour uniquement si elles font avancer le travail, jamais en arrière.
Où un sous-domaine de tunnel stable peut aider
Localhost n’est pas accessible par Google ou OpenAI, vous avez donc besoin d’une URL HTTPS publique. Le guide d’OpenAI l’admet et suggère des outils tels que ngrok, ou des environnements de développement cloud comme Replit, GitHub Codespaces, Cloudflare Workers et v0. Ce qui compte pour le travail par batch, c’est que cette URL reste la même.
- Les endpoints OpenAI et les webhooks Gemini statiques sont enregistrés une fois. Si l’URL change à chaque session, vous revenez au tableau de bord ou à l’API qui le met à jour. Un nom d’hôte fixe peut être enregistré une fois et laissé tel quel.
- Les webhooks Gemini dynamiques intègrent l’URL dans chaque travail. Vous pouvez coder un nom d’hôte stable dans
webhook_config.urisdans votre code de soumission, de sorte que chaque travail que vous lancez pointe déjà vers chez vous. - Évitez les redirections sur l’URL enregistrée. OpenAI ne suit pas les réponses
3xxet les traite comme des échecs, alors enregistrez l’URL HTTPS finale, y compris le chemin exact. - La durée de session doit correspondre à l’horizon du travail. Le README d’InstaTunnel annonce un niveau gratuit avec des sessions de 24 heures ou plus, des sous-domaines personnalisés tels que
myapp.instatunnel.my, et trois tunnels simultanés. Son niveau Pro publié coûte 5 $/mois. Vérifiez la page de tarification actuelle pour les limites avant de vous y fier. Une session de tunnel qui dure aussi longtemps qu’une fenêtre batch de 24 heures ne garantit pas une seule session couvrant tout le travail. Les réessais des fournisseurs signifient qu’une reconnexion rapide ne fait pas perdre l’événement, tant que vous revenez à la même adresse.npm install -g instatunnel instatunnel 3000 --subdomain my-app # https://my-app.instatunnel.my -> localhost:3000
Un seul tunnel suffit si vous routez par chemin (/hooks/openai, /hooks/gemini-static, /hooks/gemini-dynamic). Un tunnel séparé par intégration est optionnel, par exemple si vous voulez des journaux séparés.
Quoi qu’il en soit, gardez le projet de dev Gemini séparé de la production afin que le point d’extrémité statique ne reçoive que vos propres événements.
Checklist avant le déploiement
- Mappez les noms d’événements explicitement :
batch.completed(OpenAI) etbatch.succeeded(Gemini). - Lisez le corps brut avant que tout middleware JSON ne le touche.
- Répondez rapidement en
2xx, puis mettez en file d’attente le vrai travail. - Dédupliquez sur
webhook-id, et conservez les enregistrements de déduplication plus longtemps que la fenêtre de réessai (72 heures pour OpenAI). - Vérifiez les lignes échouées dans un batch OpenAI « completed » via
error_file_id, et recherchez une sortie partielle surbatch.expired. - N’imaginez pas que
output_file_uriest présent sur chaque événement Gemini, et vérifiez ce que vos livrais réellement contiennent. - Exécutez deux vérificateurs si vous utilisez les deux modèles Gemini, et mettez en cache les JWKS.
- N’enregistrez pas les URL qui redirigent ; OpenAI ne les suit pas.
- Ajoutez une vérification de réconciliation pour les travaux qui dépassent la période d’indisponibilité de votre point d’extrémité.
Questions fréquemment posées
Les webhooks Gemini fonctionnent-ils avec l’API Batch ?
Oui. Batch est un cas d’usage majeur, avec les événements batch.succeeded, batch.failed, batch.cancelled et batch.expired. Les webhooks couvrent aussi les Interactions et la génération vidéo.
Les webhooks Gemini sont-ils généralement disponibles ?
Le post de lancement de Google affirme qu’ils sont accessibles à tous les développeurs utilisant l’API Gemini, mais la documentation actuelle marque la fonctionnalité comme préversion. Revérifiez la documentation avant de vous baser sur des détails.
Quelle est la différence entre les webhooks Gemini statiques et dynamiques ?
Les webhooks statiques sont des points d’accès au niveau projet, créés via l’API WebhookService et signés avec un secret HMAC. Les webhooks dynamiques sont définis par requête via webhook_config et signés avec un JWT que vous vérifiez contre les clés publiques de Google.
Le webhook contient-il mes résultats de batch ?
Non. Gemini envoie une référence (tel que output_file_uri dans l’exemple de Google), et OpenAI n’envoie que l’ID du batch, après quoi vous récupérez le fichier de sortie.
Combien de temps les fournisseurs continuent-ils de réessayer ?
Google réessaie pendant 24 heures avec backoff exponentiel. OpenAI réessaie jusqu’à 72 heures avec backoff exponentiel.
Puis-je tester les webhooks OpenAI sans lancer un travail ?
Oui. La page des paramètres des webhooks du tableau de bord peut envoyer des événements de test avec des données d’exemple.
OpenAI suivra-t-il une redirection sur l’URL de mon webhook ?
Non. Les réponses 3xx sont traitées comme des échecs, alors enregistrez l’URL de destination finale.
Conclusion
Les callbacks IA asynchrones sont faciles à recevoir et difficiles à déboguer car leurs entrées sont coûteuses à reproduire. Capturez une livraison réelle, séparez vérification et traitement, simulez la récupération du résultat, et maintenez une vérification par polling pour tout ce qui dépasse votre fenêtre de réessai. Ainsi, le batch n’a plus qu’à s’exécuter une fois, et tout ce qui suit n’est qu’un fixture.
Sources
- Google : Réduire les frictions et la latence pour les travaux de longue durée avec les Webhooks dans Gemini API
- Documentation Webhooks de l’API Gemini
- OpenAI : Guide Webhooks
- OpenAI : Guide Batch API
- OpenAI API référence : événements webhook
- Spécification Standard Webhooks
- README du package npm InstaTunnel
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.