Webhooks

Les webhooks de GPT Workbench fournissent une livraison d'événements sortants vers des systèmes externes. Lorsqu'une exécution IA se termine dans un fil configuré avec des webhooks, le système envoie automatiquement les résultats aux URLs de points de terminaison que vous avez spécifiées. Cela permet une intégration en temps réel avec les services de notification, les pipelines de données, les systèmes CRM et toute autre application capable de recevoir des requêtes HTTP POST.

Vue d'ensemble

Un point de terminaison webhook est une URL de destination qui reçoit des payloads structurés lorsque certains événements se produisent dans un fil. Contrairement aux déclencheurs API (qui reçoivent des requêtes entrantes), les webhooks sont sortants : GPT Workbench pousse les données vers vos systèmes.

Caractéristiques principales :

• Les webhooks se déclenchent lorsque des exécutions automatisées se terminent (prompts programmés et déclencheurs API)
• Les payloads incluent le prompt, la réponse de l'IA, l'utilisation de tokens, les données de coût et la chronologie
• La vérification de signature HMAC-SHA256 garantit l'authenticité du payload
• La logique de réessai automatique gère les échecs de livraison transitoires
• Le suivi de livraison offre une visibilité complète sur les taux de succès et les temps de réponse

Accéder aux webhooks

1. Ouvrez le fil que vous souhaitez configurer pour la livraison sortante
2. Cliquez sur le menu Actions dans l'en-tête du fil
3. Sélectionnez Automatisations
4. Naviguez vers l'onglet Webhooks

L'onglet affiche tous les points de terminaison webhook configurés pour le fil actuel, ainsi que les statistiques de livraison et les indicateurs de statut.

Configurer un point de terminaison webhook

Cliquez sur Nouveau ou Créer un point de terminaison webhook pour ouvrir le formulaire de création.

Champs de configuration

Nom (obligatoire) Un libellé descriptif pour le point de terminaison webhook. Utilisez des noms identifiant la destination, tels que « Notifications Slack » ou « Ingestion entrepôt de données ».

URL du webhook (obligatoire) Le point de terminaison HTTPS qui recevra les requêtes POST. Cette URL doit être publiquement accessible et capable d'accepter des payloads JSON.

Exemple :

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Secret du webhook (optionnel) Un secret partagé utilisé pour générer une signature HMAC-SHA256 pour chaque livraison. Lorsqu'il est configuré, chaque requête inclut un en-tête X-Hub-Signature-256 contenant la signature. Votre application réceptrice doit vérifier cette signature pour confirmer que le payload à été envoyé par GPT Workbench et n'a pas été altéré.

En-têtes personnalisés (optionnel) Des en-têtes HTTP supplémentaires à inclure avec chaque requête de livraison. Utilisez-les pour transmettre des jetons d'autorisation, des surcharges de type de contenu ou tout en-tête requis par le système récepteur.

Cliquez sur + Ajouter un en-tête pour ajouter des paires clé-valeur. Exemples courants :

En-tête	Valeur	Objectif
Authorization	Bearer sk-votre-jeton	Authentification API
X-Source	gpt-workbench	Identification de la source
X-Environment	production	Marquage de l'environnement

Format du payload

Lorsqu'un webhook se déclenche, il envoie un payload JSON avec la structure suivante :

{
  "event": "exécution.completed",
  "triggerId": "550e8400-e29b-41d4-a716-446655440000",
  "triggerName": "Programme de rapport quotidien",
  "exécution": {
    "jobId": "661f9511-b38a-42c5-9e2a-557766880000",
    "runId": "772a0622-c49b-53d6-af3b-668877990000",
    "prompt": "Générer le résumé des ventes du jour",
    "run": {
      "totalCostUsd": 0.0342,
      "totalTokens": 4521,
      "startedAt": "2026-03-29T09:00:01.000Z",
      "completedAt": "2026-03-29T09:00:12.450Z",
      "durationMs": 11450,
      "messages": [...]
    },
    "queuedAt": "2026-03-29T09:00:00.000Z",
    "completedAt": "2026-03-29T09:00:12.450Z",
    "durationMs": 12450
  },
  "threadId": "883b1733-d50c-64e7-bg4c-779988001111",
  "userId": 42
}

Champ	Description
event	Le type d'événement (actuellement exécution.completed)
triggerId	Identifiant du programme ou du déclencheur API ayant initié l'exécution
triggerName	Nom lisible du déclencheur
exécution.jobId	Identifiant unique du travail
exécution.runId	Identifiant de l'enregistrement d'exécution associé
exécution.prompt	Le texte du prompt envoyé
exécution.run.totalCostUsd	Coût total de l'exécution en USD
exécution.run.totalTokens	Nombre total de tokens consommés
exécution.run.durationMs	Durée de traitement en millisecondes
exécution.run.messages	Tableau des messages de réponse de l'IA
threadId	Le fil où l'exécution à eu lieu
userId	L'utilisateur propriétaire de l'automatisation

Vérification de signature

Lorsqu'un secret de webhook est configuré, chaque livraison inclut un en-tête X-Hub-Signature-256. Cet en-tête contient un condensé hexadécimal HMAC-SHA256 calculé sur le corps brut de la requête en utilisant votre secret comme clé.

Pour vérifier la signature dans votre application réceptrice :

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

Utilisez toujours une fonction de comparaison à temps constant pour prévenir les attaques par canal temporel.

Suivi de livraison

L'onglet webhooks fournit des statistiques de livraison pour chaque point de terminaison configuré.

Tableau de bord des statistiques

Chaque point de terminaison webhook affiche trois métriques :

• Total des livraisons : nombre cumulé de tentatives de livraison
• Taux de succès : pourcentage de livraisons ayant reçu une réponse 2xx
• Temps de réponse moyen : temps moyen de réponse du serveur récepteur

Journaux de livraison

La section des livraisons récentes affiche les enregistrements individuels de livraison, contenant chacun :

Champ	Description
Statut	succès, échoué, en attente ou en réessai
Code de réponse	Code HTTP retourné par le serveur récepteur
Temps de réponse	Temps de réponse du serveur (en millisecondes)
Tentatives	Nombre de tentatives de livraison effectuées (sur le maximum de tentatives)
Horodatage	Date et heure d'initiation de la livraison

Logique de réessai

Lorsqu'une livraison échoue (réponse non-2xx ou erreur réseau), GPT Workbench réessaie automatiquement avec une stratégie de délai exponentiel :

Tentative	Délai	Description
1er réessai	5 secondes	Réessai immédiat pour les erreurs transitoires
2e réessai	15 secondes	Court délai pour une indisponibilité temporaire
3e réessai	60 secondes	Dernière tentative avec un intervalle plus long

Après 3 tentatives de réessai échouées, la livraison est marquée comme définitivement échouée. Le délai d'attente de chaque tentative est de 30 secondes.

Réessai manuel

Pour les livraisons échouées qui n'ont pas épuisé toutes les tentatives de réessai, un bouton Réessayer apparaît dans le journal de livraison. Cliquez dessus pour mettre immédiatement en file d'attente une nouvelle tentative de livraison avec le payload original.

Gérer les points de terminaison webhook

Activer/Désactiver

Cliquez sur Désactiver pour arrêter temporairement les livraisons vers un point de terminaison sans le supprimer. Les webhooks désactivés ne reçoivent aucun payload, même lorsque les exécutions se terminent. Cliquez sur Activer pour reprendre les livraisons.

Test

Cliquez sur le bouton Test sur n'importe quel webhook pour envoyer un payload de test. La fenêtre de test affiche :

• L'URL du point de terminaison de destination
• Un payload JSON modifiable prérempli avec des données d'exemple
• Des informations sur l'inclusion de la signature HMAC (lorsqu'un secret est configuré)

Utilisez les livraisons de test pour vérifier la connectivité et le traitement du payload avant d'activer l'automatisation en production.

Suppression

Retirez un point de terminaison webhook en le supprimant de la liste des webhooks. Cela arrête toutes les livraisons futures et supprimé la configuration du point de terminaison. Les journaux de livraison existants sont conservés pour référence.

Cas d'utilisation

Notifications Slack

Livrez les résumés et rapports générés par l'IA directement dans un canal Slack en utilisant une URL de webhook entrant.

URL : https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Votre intégration Slack peut analyser le champ exécution.run.messages pour extraire la réponse de l'IA et la formater pour l'affichage dans le canal.

Ingestion dans un entrepôt de données

Poussez les résultats d'exécution vers un point de terminaison de pipeline de données pour le stockage et l'analyse. Incluez des en-têtes personnalisés pour l'authentification et utilisez les données de coût et de tokens pour suivre l'utilisation de l'IA dans votre organisation.

Mises à jour CRM

Livrez les résultats d'analyse IA à votre système CRM. Par exemple, lorsqu'un prompt programmé génère une évaluation de risque d'affaire, le webhook peut pousser les résultats vers un point de terminaison CRM personnalisé qui met à jour l'enregistrement de l'affaire.

Alertes d'incidents

Configurez un webhook vers un service d'alerte (PagerDuty, Opsgenie, passerelle email). Lorsqu'un prompt de surveillance détecte des anomalies, le webhook livre l'analyse de l'IA à votre système de gestion d'incidents pour le triage.

Pipeline de génération de documents

Utilisez les webhooks pour alimenter un pipeline de génération de documents avec du contenu généré par l'IA. Le système récepteur prend la sortie de l'IA depuis le tableau de messages et produit des PDF, des présentations ou d'autres livrables formatés.

Bonnes pratiques

1. Configurez toujours un secret de webhook. La vérification de signature empêche le traitement de payloads non autorisés par votre point de terminaison récepteur.

2. Gérez les réessais de manière idempotente. Votre point de terminaison récepteur peut recevoir le même payload plusieurs fois lors des tentatives de réessai. Concevez votre logique de traitement pour gérer les livraisons en double de manière élégante.

3. Répondez rapidement. Le délai d'attente de livraison est de 30 secondes. Votre point de terminaison doit accuser réception rapidement et effectuer le traitement lourd de manière asynchrone.

4. Surveillez les taux de succès. Un taux de succès en déclin peut indiquer des problèmes de point de terminaison, des problèmes réseau ou l'expiration de jetons d'authentification. Traitez les échecs avant qu'ils ne s'accumulent.

5. Utilisez les livraisons de test avant la production. Vérifiez que votre point de terminaison analyse correctement le format du payload, valide les signatures et traite les données comme prévu.

6. Sécurisez vos points de terminaison. En plus des signatures webhook, envisagez des restrictions d'IP, l'application de TLS et des en-têtes d'authentification pour protéger vos points de terminaison récepteurs.