Déclencheurs API

Les déclencheurs API vous permettent de créer des points de terminaison HTTP personnalisés qui initient des conversations IA dans GPT Workbench depuis des systèmes externes. Chaque déclencheur génère une URL unique qui accepte des requêtes POST avec un prompt en payload. Lorsqu'il est appelé, le système met le prompt en file d'attente pour traitement dans le fil associé, en utilisant son contexte complet, son prompt système et ses outils. Cela permet une intégration programmatique entre votre infrastructure existante et GPT Workbench.

Vue d'ensemble

Un déclencheur API est un point de terminaison sécurisé, authentifié par jeton, lié à un fil de discussion spécifique. Les systèmes externes envoient une requête HTTP POST contenant un prompt, et GPT Workbench le traite exactement comme si un utilisateur avait saisi le prompt dans le fil. La réponse est générée de manière asynchrone et peut optionnellement être livrée à une URL de webhook une fois terminée.

Caractéristiques principales :

• Chaque déclencheur possède un jeton API unique, généré aléatoirement, intégré dans l'URL
• Aucun en-tête d'authentification supplémentaire n'est requis ; le jeton lui-même sert d'identifiant
• La limitation de débit, la liste blanche d'IP et l'exécution éphémère sont configurables par déclencheur
• Les journaux d'exécution suivent chaque invocation avec le statut, la chronologie et les métadonnées

Accéder aux déclencheurs API

1. Ouvrez le fil que vous souhaitez exposer via API
2. Cliquez sur le menu Actions dans l'en-tête du fil
3. Sélectionnez Automatisations
4. Naviguez vers l'onglet Déclencheurs API

L'onglet affiche tous les déclencheurs configurés pour le fil actuel, ainsi que le nombre d'appels, les paramètres de limitation de débit et les indicateurs de statut.

Créer un déclencheur

Cliquez sur Nouveau ou Créer un déclencheur API pour ouvrir le formulaire de création.

Champs de configuration

Nom (obligatoire) Un libellé descriptif pour le déclencheur. Utilisez des noms identifiant l'intégration, tels que « Hook affaire conclue CRM » ou « Rapporteur pipeline CI/CD ».

Description (optionnel) Une explication plus détaillée de l'objectif du déclencheur. Utile pour la documentation d'équipe et l'audit.

Limite de débit (par heure) Le nombre maximum d'appels autorisés par heure. Par défaut : 100. Définissez cette valeur en fonction de votre trafic prévu et de votre budget. Les appels dépassant la limité reçoivent une réponse 429 Too Many Requests.

Exécution éphémère Lorsqu'elle est activée, le prompt et la réponse de l'IA ne sont pas stockés dans l'historique de conversation du fil. C'est utile pour les intégrations sans état où vous n'avez besoin que du résultat de l'IA livré via webhook ou journalisé dans l'historique d'exécution, sans accumuler de messages dans le fil.

Liste blanche d'IP (optionnel) Restreignez l'accès à des adresses IP ou des blocs CIDR spécifiques. Entrez une entrée par ligne. Lorsqu'elle est configurée, les requêtes provenant d'IP non autorisées reçoivent une réponse 403 Forbidden. Laissez vide pour autoriser toutes les IP.

Exemple :

192.168.1.0/24
10.0.0.1
203.0.113.0/24

URL du déclencheur et authentification

Après avoir créé un déclencheur, le système génère une URL webhook unique contenant le jeton API :

POST https://engine.votreinstance.com/webhooks/trigger/{apiToken}

Le jeton API est une chaîne de 64 caractères intégrée directement dans l'URL. Aucun en-tête Authorization ni paramètre de clé API n'est nécessaire. Traitez cette URL comme un secret : toute personne disposant de l'URL peut invoquer le déclencheur.

Régénérer le jeton

Cliquez sur le bouton de régénération pour créer un nouveau jeton API. Cela invalide immédiatement l'URL précédente. Tous les systèmes externes utilisant l'ancienne URL doivent être mis à jour. Utilisez cette fonctionnalité lorsque vous soupçonnez que l'URL à été compromise.

Copier l'URL

Cliquez sur le bouton de copie pour copier l'URL webhook complète dans votre presse-papiers afin de l'utiliser dans les configurations de systèmes externes.

Appeler le déclencheur

Format de la requête

POST /webhooks/trigger/{apiToken}
Content-Type: application/json

{
  "prompt": "Votre texte de prompt ici",
  "source": "système-externe"
}

Champ	Type	Obligatoire	Description
prompt	chaîne	Oui	Le texte du prompt à envoyer au fil (max 50 000 caractères)
source	chaîne	Non	Identifiant optionnel du système appelant (max 100 caractères)

Format de la réponse

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Prompt queued for processing",
  "estimatedWaitTime": "2-30 seconds"
}

Le point de terminaison retourne 202 Accepted immédiatement. Le traitement s'effectue de manière asynchrone.

Vérifier le statut d'exécution

GET /webhooks/trigger/{apiToken}/status

Retourne le statut actuel de la dernière exécution du déclencheur.

Réponses d'erreur

Code HTTP	Signification
400	Format de requête invalide ou champs obligatoires manquants
403	IP non autorisée
404	Jeton API invalide ou expiré
429	Limite de débit dépassée

Exemple avec cURL

curl -X POST https://engine.votreinstance.com/webhooks/trigger/{apiToken} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Générer un résumé quotidien des tickets de support ouverts", "source": "helpdesk"}'

Gérer les déclencheurs

Afficher les déclencheurs

La liste des déclencheurs affiche chaque déclencheur avec son nom, son statut actif/inactif, le nombre total d'appels et la limité de débit. Cliquez sur la flèche de développement pour voir les détails complets, y compris l'URL webhook, la liste blanche d'IP et les statistiques d'utilisation.

Basculer actif/inactif

Utilisez l'interrupteur pour activer ou désactiver un déclencheur. Les déclencheurs désactivés retournent 404 pour toutes les requêtes entrantes. Désactiver un déclencheur ne le supprimé pas ni son historique d'exécution.

Statistiques d'utilisation

Chaque déclencheur suit :

• Total des appels : nombre cumulé d'invocations réussies
• Dernier déclenchement : horodatage du dernier appel
• Limite de débit : nombre maximum d'appels par heure configuré

Supprimer un déclencheur

Cliquez sur le bouton de suppression pour retirer définitivement un déclencheur. Une boîte de dialogue de confirmation apparaît. La suppression invalide l'URL, retire la configuration du déclencheur et supprimé tous les journaux d'exécution associés. Cette action est irréversible.

Journaux d'exécution

Cliquez sur Voir les journaux d'exécution sur un déclencheur développé pour consulter son historique d'invocation.

Chaque entrée de journal comprend :

Champ	Description
Statut	en file d'attente, en cours, terminé, échoué ou limité par le taux
Prompt	Le texte du prompt envoyé
Mis en file à	Horodatage de réception de la requête
ID du travail	Identifiant unique du travail d'exécution
ID de l'exécution	Identifiant de l'exécution associée (lorsque le traitement à démarré)
Message d'erreur	Détails sur l'échec
Métadonnées	IP du client, agent utilisateur et horodatage de la requête

Les journaux sont conservés pour les 50 dernières exécutions par déclencheur.

Considérations de sécurité

1. Traitez l'URL du déclencheur comme un secret. Le jeton API intégré dans l'URL est le seul mécanisme d'authentification. Stockez-le de manière sécurisée dans vos systèmes externes en utilisant des variables d'environnement ou des outils de gestion de secrets.

2. Utilisez la liste blanche d'IP pour les intégrations de production. Restreignez l'accès aux plages d'IP connues pour empêcher les invocations non autorisées, en particulier pour les déclencheurs avec des limités de débit élevées.

3. Définissez des limités de débit prudentes. Commencez avec une limité basse et augmentez-la selon les besoins. Chaque invocation consomme des tokens IA et engendre un coût.

4. Régénérez les jetons périodiquement. Renouvelez les jetons API selon un calendrier régulier ou chaque fois que des membres de l'équipe ayant accès quittent l'organisation.

5. Surveillez les journaux d'exécution. Examinez les journaux pour détecter des schémas inattendus tels que des appels provenant de sources inconnues, des taux d'échec élevés ou un contenu de prompt inhabituel.

Cas d'utilisation

Récepteur de webhooks pour événements CRM

Créez un déclencheur qui traite les événements CRM (affaire conclue, contact créé) en envoyant des prompts structurés qui référencent les données de l'événement.

curl -X POST https://engine.votreinstance.com/webhooks/trigger/{token} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Une nouvelle affaire à été conclue : Acme Corp, 50 000 EUR ARR. Générez un brouillon d'\''email d'\''accueil d'\''intégration pour le contact principal.", "source": "hubspot"}'

Intégration pipeline CI/CD

Déclenchez une analyse IA des résultats de build ou de déploiement depuis votre système CI/CD.

curl -X POST https://engine.votreinstance.com/webhooks/trigger/{token} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Le build #1234 à échoué sur la branche feature/auth-redesign. Erreur : erreur de compilation TypeScript dans auth.service.ts ligne 47. Analysez la cause probable et suggérez une correction.", "source": "github-actions"}'

Traitement de soumissions de formulaires

Connectez un formulaire web à un déclencheur qui traite les soumissions utilisateur avec l'IA.

curl -X POST https://engine.votreinstance.com/webhooks/trigger/{token} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Nouvelle demande de support de jean@acme.fr : Je ne peux plus exporter les rapports en PDF depuis la dernière mise à jour. Catégorisez ce problème, évaluez sa gravité et rédigez une réponse.", "source": "formulaire-support"}'

Rapports planifiés depuis un système externe

Utilisez un planificateur externe (cron, Planificateur de tâches, planificateur cloud) pour déclencher des analyses IA périodiques.

# Exécution quotidienne à 8h00 via cron système
0 8 * * * curl -s -X POST https://engine.votreinstance.com/webhooks/trigger/{token} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Générez le briefing matinal du jour en utilisant les dernières données de nos tableaux de bord.", "source": "cron"}'