Déclencher un Croco Agent depuis une application externe avec un webhook entrant

Un webhook entrant permet à une application externe de lancer un Croco Agent dès qu'un événement se produit chez elle. Votre boutique enregistre une commande, l'agent reçoit les données, retrouve le client et ajoute une note sur sa fiche. Vous n'avez ni automatisation intermédiaire à créer, ni champ à mapper un par un.

Ce guide complète les déclencheurs planifiés, qui lancent un agent selon un horaire. Ici, c'est un événement extérieur qui donne le départ.

Ce que vous y gagnez

• Connexion directe : aucune automatisation à construire entre l'application et l'agent.
• Lecture par l'agent : il interprète les données reçues selon ses instructions.
• Formats variés : JSON, données de formulaire, XML, texte brut et requêtes multipart.
• Plusieurs déclencheurs : une URL distincte par type d'événement.
• Sécurité optionnelle : vérification des requêtes par jeton partagé.
• Protection contre les doublons : certaines requêtes répétées ne relancent pas l'agent.
• Suivi : chaque réception et son résultat restent consultables.

Comment cela fonctionne

1. L'application externe envoie une requête HTTP POST à l'URL unique du déclencheur.
2. CrocoClick vérifie la requête, si la vérification est activée.
3. L'agent reçoit les données comme point de départ.
4. Il les traite selon ses instructions.
5. L'exécution apparaît dans son flux d'activité.

Données acceptées et limites

L'agent peut lire le corps de la requête, les paramètres de requête et les en-têtes autorisés. Vous pouvez par exemple lui demander de chercher l'adresse email du client dans customer.email.

Le code HTTP 202 signifie que la requête est acceptée pour traitement, pas que l'agent a terminé. Avant une intégration à fort volume, vérifiez à quel niveau s'applique la limite de débit.

Configurer le webhook

1. Ouvrir l'agent

Allez dans Agents IA puis CrocoAgent. Sélectionnez un Croco Agent existant dans la liste puis cliquez sur Modifier l'agent, ou créez-en un avec le bouton + à côté de Rechercher des agents.

2. Ajouter le déclencheur

Dans Déclencheurs, cliquez sur Ajouter un déclencheur, sélectionnez Webhook entrant, puis nommez-le clairement, par exemple Nouvelle commande.

3. Rédiger les instructions

Expliquez au constructeur IA comment utiliser les données reçues. Par exemple : « Quand une nouvelle commande arrive par le webhook, retrouve le client grâce à son adresse email et crée une note interne contenant le détail de la commande. » Si l'application utilise des noms de champs précis, citez-les, comme customer.email.

4. Sécuriser les requêtes

1. Ouvrez les réglages du déclencheur Webhook entrant.
2. Sous Vérification, sélectionnez En-tête de jeton partagé si vous voulez authentifier les requêtes.
3. Générez le jeton et copiez-le en lieu sûr : il n'est affiché qu'au moment de sa génération.
4. Enregistrez le déclencheur.

L'application doit alors envoyer le jeton dans l'un de ces en-têtes : X-Webhook-Token ou Authorization: Bearer. Une requête sans jeton valide est rejetée avec un code 401.

5. Publier et copier l'URL

Enregistrez l'agent et le déclencheur, relisez les instructions, puis publiez le Croco Agent. Ouvrez ensuite les réglages Webhook entrant et cliquez sur Copier à côté de URL du webhook. L'URL est générée à l'enregistrement et devient active à la publication.

6. Connecter l'application externe

Dans les réglages webhook ou HTTP de votre application, choisissez POST, collez l'URL, indiquez les données à envoyer, ajoutez le jeton dans les en-têtes si la vérification est activée, puis enregistrez. Le détail dépend de l'application.

7. Tester

Envoyez une requête de test depuis l'application, revenez dans les réglages Webhook entrant, contrôlez Dernière requête et ouvrez l'exécution liée si elle est proposée.

8. Contrôler l'exécution

Dans le panneau Détails de l'agent, ouvrez l'onglet Activité, filtrez sur Triggers (libellé encore en anglais à l'écran), sélectionnez l'exécution du webhook reçu, vérifiez la requête et le résultat de l'agent, puis ajustez ses instructions si nécessaire.

Gérer plusieurs événements

Un même agent peut avoir plusieurs webhooks entrants, chacun avec son nom, son URL et son message. Par exemple, Nouvelle commande traite un achat et Remboursement demandé examine une demande de remboursement. Décrivez dans les instructions comment traiter chaque type de données.

Comprendre les réponses du webhook

Requêtes en double : si l'application renvoie un événement, CrocoClick peut reconnaître les doublons pris en charge grâce à une clé d'idempotence, un identifiant d'événement ou un corps identique sur une courte période. Il renvoie alors l'exécution d'origine au lieu d'en créer une autre.

Questions fréquentes

Faut-il une automatisation pour utiliser ce webhook ?

Non. Le déclencheur lance directement le Croco Agent.

La vérification par jeton est-elle obligatoire ?

Non, elle est optionnelle, mais recommandée si l'application peut envoyer des en-têtes d'authentification.

Que faire si j'ai perdu mon jeton ?

Régénérez-le dans les réglages du déclencheur, puis mettez à jour l'application externe.

Que se passe-t-il si je dépublie l'agent ?

Son URL de webhook cesse d'accepter les requêtes.

Où voir les données reçues ?

Dans le flux d'activité de l'agent, sur l'exécution Webhook reçu correspondante.