Webhook générique — recettes prêtes à l'emploi

Pour qui est cet article

Vous voulez connecter votre agent à un outil pour lequel Sens Ai ne fournit pas de modèle dédié : Notion, HubSpot, Pipedrive, Airtable, votre CRM maison, ou n’importe quel service qui accepte un webhook. Le modèle Webhook générique est fait pour ça.

Cet article complète Créer une action personnalisée avec trois recettes concrètes : Notion (créer une page), HubSpot (créer un contact), et Zapier / Make / n8n (déclencher un scénario qui fera le reste).

Si un modèle dédié existe pour votre outil (JIRA, Slack, Calendly, e-mail via Resend), utilisez-le : il est mieux adapté et déjà validé. Le Webhook générique reste la solution de repli.

Comment fonctionne le Webhook générique

Le connecteur

Il se crée depuis le menu du haut Intégrations › onglet Catalogue › Configurer sur Webhook générique. Vous renseignez :

• Nom — pour vous y retrouver (ex. : Zapier — Notion Leads) ;
• URL de base — l’adresse exacte qui recevra l’appel, en https:// (pas de paramètre dynamique) ;
• Type d’authentification — none (aucun en-tête d’authentification), bearer (Sens Ai envoie Authorization: Bearer <valeur>) ou header (Sens Ai envoie l’en-tête nommé dans Nom du header, avec la valeur telle quelle) ;
• Valeur d’authentification — chiffrée au repos, jamais réaffichée. Avec bearer, saisissez le jeton seul : Sens Ai ajoute Bearer lui-même. Pour un autre schéma (Basic …), choisissez header, le nom Authorization et la valeur complète ;
• Nom du header — utilisé avec le type header (Authorization par défaut), par exemple X-API-Key.

Le test du connecteur ne prouve pas que l’authentification marche. Le bouton Tester vérifie que l’adresse répond, en envoyant l’authentification du connecteur. « Connexion réussie. » ou « Serveur joignable (HTTP …). » ne garantit pas que votre outil accepte la clé ; une réponse 401 ou 403 fait échouer le test, sans changer le statut du connecteur. Seul Tester l’action (sur la page de l’action) envoie un vrai appel.

L’action

Dans le menu de gauche de l’agent : Configuration Agent › Compétences › onglet Catalogue › Configurer sur Webhook générique. Vous choisissez :

• le Connecteur ;
• la Méthode HTTP — GET, POST, PUT, PATCH, DELETE (POST par défaut).

L’agent remplit un seul champ, body, qu’il rédige à la volée à partir de la conversation.

Ce qui part à l’exécution

• l’URL exacte du connecteur ;
• les en-têtes Content-Type: application/json, l’en-tête d’authentification construit à partir du connecteur (voir plus haut) et Idempotency-Key (unique par conversation, message et action — utile pour ignorer un doublon de votre côté) ;
• avec les méthodes POST, PUT et PATCH, un corps JSON de la forme (avec GET ou DELETE, aucun corps n’est envoyé) :

{
  "data": "<contenu rédigé par l'agent>",
  "collected": { "email_client": "marie@acme.fr" }
}

La clé collected n’apparaît que si l’action a des champs à collecter et que le visiteur en a donné : une propriété par champ, nommée d’après le Nom du champ.

Le délai d’attente est de 10 secondes : au-delà, l’action échoue.

Important — l’enveloppe { "data": ... }. L’agent ne peut pas envoyer directement le JSON précis qu’attend une API tierce (le corps exact de Notion ou de HubSpot, par exemple). Ce qu’il produit est toujours placé dans { "data": "…" }. Pour ces API, deux options : (1) passer par Zapier ou Make, qui savent lire cette enveloppe et reformater ; (2) écrire un petit relais (Cloudflare Worker, fonction serverless, mini-serveur) qui reçoit { "data": "…" } et appelle l’API tierce au bon format.

Dire à l’agent quoi envoyer

Sens Ai donne à l’agent une consigne pour ce modèle : n’appeler le webhook que si le visiteur le demande explicitement, et lui demander quelles informations transmettre. Pour cadrer le contenu de body, utilisez :

• le Nom de l’action, que l’agent lit pour reconnaître l’action (ex. : « Enregistrer un lead dans Notion ») ;
• la Description de l’action, qui s’ajoute à la consigne du modèle (ex. : « Envoyer un body JSON avec les clés name, email, company et message ») ;
• une règle de réponse sur la page Comportement (voir Règles de sécurité et règles de réponse), par exemple :
  • Scénario : « Le visiteur veut être recontacté et laisse ses coordonnées » ;
  • Faire : « Utiliser l’action Enregistrer un lead dans Notion, avec un body JSON contenant les clés name, email, company et message » ;
  • Éviter : « Envoyer le lead sans e-mail ».

Pour une information à obtenir à chaque fois (e-mail, téléphone…), ajoutez plutôt des champs à collecter : leurs valeurs arrivent dans la clé collected, séparées de data. Testez ensuite vos scénarios depuis l’entrée Test du menu de gauche.

Les recettes ci-dessous tiennent compte de ces contraintes.

Recette 1 — Notion (créer une page) via un relais

L’API Notion attend un corps JSON très structuré (parent, properties.Name.title[0].text.content, etc.). Le Webhook générique ne peut pas le produire directement : la méthode propre est d’utiliser Zapier ou Make en relais.

Recette 1a — Via Zapier (recommandée)

1. Dans Zapier, créez un Zap avec Trigger = Webhooks by Zapier → Catch Hook. Copiez l’URL fournie par Zapier (ex. https://hooks.zapier.com/hooks/catch/12345/abcdef/).
2. Ajoutez une Action = Notion → Create Database Item. Connectez votre espace Notion, choisissez la base cible (ex. « Leads ») et associez les champs à ceux de data.
3. Côté Sens Ai, créez le connecteur Webhook générique :
   • URL de base : l’URL Zapier de l’étape 1 ;
   • Type d’authentification : none (Zapier n’exige pas d’authentification sur un Catch Hook) ;
   • Nom : Zapier — Notion Leads.
4. Créez l’action Webhook générique :
   • Nom : Enregistrer un lead dans Notion ;
   • Connecteur : Zapier — Notion Leads ;
   • Méthode HTTP : POST.
5. Ajoutez la règle de réponse décrite plus haut (clés name, email, company, message).
6. Testez l’action (section Test, champ body, voir Tester et déboguer) : Zapier doit recevoir l’appel, et une ligne doit apparaître dans votre base Notion.

Côté contenu, l’agent enverra typiquement :

{ "data": "{\"name\":\"Marie Dupont\",\"email\":\"marie@acme.fr\",\"company\":\"Acme\",\"message\":\"Demande de démo\"}" }

Dans Zapier, récupérez les champs via data (Zapier sait souvent analyser le JSON imbriqué ; sinon, ajoutez une étape Code by Zapier → Run JavaScript avec JSON.parse(inputData.data)).

Recette 1b — Via Make

Identique à Zapier, en remplaçant l’étape 1 par un scénario Make avec un module Webhooks → Custom webhook (copiez l’URL générée), puis un module Notion → Create a Database Item.

Recette 1c — Sans relais (avancé)

Si vous ne voulez pas dépendre de Zapier ou Make, écrivez un petit Cloudflare Worker (ou une fonction serverless, ou une route de votre serveur) qui :

1. reçoit la requête POST de Sens Ai avec { "data": "…JSON…" } ;
2. fait JSON.parse(body.data) ;
3. appelle l’API Notion https://api.notion.com/v1/pages avec le contenu reformaté, votre en-tête Notion-Version et Authorization: Bearer secret_xxx.

Le connecteur Sens Ai pointe alors vers l’adresse de votre relais, pas vers Notion.

Recette 2 — HubSpot (créer un contact) via un relais

L’API HubSpot attend un corps de la forme { "properties": { "email": "...", "firstname": "..." } }. Comme pour Notion, l’enveloppe { "data": "..." } empêche un appel direct. Le scénario recommandé est le même.

Recette 2a — Via Zapier (recommandée)

1. Dans Zapier, créez un Zap avec Trigger = Webhooks by Zapier → Catch Hook. Copiez l’URL.
2. Action = HubSpot → Create or Update Contact. Connectez votre portail HubSpot et associez les champs depuis data (email, firstname, lastname, phone, company…).
3. Côté Sens Ai :
   • Connecteur Webhook générique : URL = l’URL Zapier, authentification none, nom Zapier — HubSpot Contacts ;
   • Action Webhook générique : ce connecteur, méthode POST, nom « Enregistrer un contact dans HubSpot » ;
   • Règle de réponse : Scénario « Le visiteur laisse ses coordonnées », Faire « Utiliser l’action Enregistrer un contact dans HubSpot, avec un body JSON contenant email, firstname, lastname, et si possible phone et company ».
4. Testez l’action, puis vérifiez la création du contact dans HubSpot → Contacts.

Recette 2b — Appel direct HubSpot (déconseillé)

Vous pourriez pointer le connecteur sur https://api.hubapi.com/crm/v3/objects/contacts avec votre jeton privé HubSpot. Mais le corps envoyé sera { "data": "…chaîne JSON…" }, que l’API HubSpot refuse (erreur 400). C’est précisément pour ce cas que le relais est nécessaire.

Recette 3 — Zapier / Make / n8n (déclencher un scénario)

C’est la recette la plus naturelle : Zapier, Make et n8n sont faits pour recevoir un contenu générique et l’orchestrer ensuite vers la destination finale. L’enveloppe { "data": "..." } n’est pas un problème : vous la déballez de leur côté.

Recette 3a — Zapier (Catch Hook)

1. Dans Zapier, créez un Zap avec Trigger = Webhooks by Zapier → Catch Hook. Copiez l’URL.
2. Ajoutez les actions Zapier souhaitées : Slack, Google Sheets, Mailchimp, Salesforce, Trello, etc.
3. Côté Sens Ai : connecteur Webhook générique (URL Zapier, authentification none, nom Zapier — <nom du Zap>), action Webhook générique en POST, avec un Nom qui dit clairement à quoi elle sert.
4. Pendant l’étape Test trigger de Zapier, lancez Tester l’action dans Sens Ai : Zapier capture le contenu réel { "data": "…" } et vous pouvez associer les champs.

Recette 3b — Make (Custom Webhook)

1. Dans Make, créez un scénario avec un module Webhooks → Custom webhook → Add → copiez l’URL générée.
2. Cliquez sur Run once dans Make pour qu’il écoute.
3. Côté Sens Ai : connecteur Webhook générique pointant vers l’URL Make, action Webhook générique en POST.
4. Lancez Tester l’action dans Sens Ai : Make enregistre la structure du contenu, et vous pouvez ensuite enchaîner Notion, HubSpot, Airtable, Gmail, etc.

Recette 3c — n8n (auto-hébergé)

Créez un workflow avec un nœud Webhook en POST. Pour sécuriser l’appel, activez l’authentification Header Auth côté n8n, avec un nom d’en-tête (par exemple X-N8N-Token) et une valeur secrète. Côté Sens Ai, choisissez le type header, le même Nom du header et la même Valeur d’authentification. Si n8n est configuré en Bearer Auth, choisissez le type bearer et saisissez le jeton seul.

Limites à connaître avant de promettre quoi que ce soit

• Corps toujours placé dans { "data": "<texte>" } (plus collected, s’il y a des champs à collecter). Les API qui exigent une structure JSON précise (Notion, HubSpot, Stripe, Airtable…) ne peuvent pas être appelées directement. Passez par Zapier, Make ou un relais.
• Une seule URL par connecteur. L’action ne peut pas la modifier. Pour viser plusieurs adresses, créez plusieurs connecteurs.
• Pas de paramètre dynamique dans l’URL. Pas de ?id=… ni de segment variable.
• Un seul en-tête d’authentification, Authorization: Bearer … ou l’en-tête nommé de votre choix. Les noms Host, Content-Type, Content-Length, User-Agent et ceux qui commencent par X-SensAI- sont refusés, comme une valeur avec des accents ou des sauts de ligne : l’action échoue alors avec « L’authentification du connecteur ne peut pas être envoyée (valeur ou nom d’en-tête invalide) ».
• HTTPS obligatoire. Une adresse en http:// est acceptée dans le connecteur, mais l’action échoue à l’exécution.
• Pas de redirection. Une réponse 3xx compte comme un échec : utilisez l’adresse finale.
• Réponse non analysée. Après un appel réussi, l’agent sait seulement que « Votre demande a bien été transmise. » : il ne peut pas annoncer au visiteur un numéro renvoyé par votre outil. Exception : si votre outil répond avec succès en annonçant du JSON (Content-Type: application/json) mais avec un contenu illisible ou vide, l’agent reçoit à la place les 500 premiers caractères de la réponse brute (rien si elle est vide).
• Délai de 10 secondes. Zapier et Make répondent en général en moins d’une seconde sur un webhook de réception.
• Pas de nouvelle tentative. En cas d’erreur 5xx ou de délai dépassé, l’action est marquée en échec et n’est pas relancée.
• Méthodes GET et DELETE peu utiles. Avec GET ou DELETE, aucun corps n’est envoyé et l’URL est fixe : réservez-les aux cas où l’adresse seule suffit.

Bientôt disponible. Vous pourrez créer une action personnalisée qui envoie un JSON libre, avec des informations typées collectées auprès du visiteur, et dont l’agent exploite la réponse.

Dépannage

Erreur 400 — Bad Request

La destination refuse le contenu. Cause la plus fréquente : le connecteur pointe directement sur l’API tierce (Notion, HubSpot, Airtable) au lieu d’un relais. Vérifiez le format attendu, et insérez un Zap ou un scénario Make si nécessaire.

Erreur 401 ou 403 — Unauthorized / Forbidden

L’authentification est refusée. À l’exécution, Sens Ai envoie Authorization: Bearer <valeur> (type bearer), l’en-tête nommé dans Nom du header avec la valeur (type header), ou aucun en-tête (type none).

• Le connecteur a passé le test mais l’appel réel échoue en 401. Le test du connecteur vérifie que l’adresse répond, pas que votre outil accepte la clé. Relancez Tester l’action après chaque correction.
• Type bearer avec une valeur qui commence déjà par Bearer : l’en-tête devient Bearer Bearer …. Correctif : saisissez le jeton seul.
• Votre destination exige un autre en-tête (ex. X-API-Key) : choisissez le type header et indiquez ce nom dans Nom du header.
• Authentification Basic : type header, Nom du header Authorization, et la valeur complète encodée en base64 (Basic dXNlcjpwYXNz).
• Type none : aucun en-tête n’est envoyé, même si une valeur est saisie. Choisissez bearer ou header.

Erreur 404 — Not Found

L’URL de base du connecteur est incorrecte. Recopiez-la depuis Zapier, Make ou votre serveur, sans espace en début ou en fin.

Erreur ou délai côté Zapier

Si le Zap échoue côté Zapier alors que Sens Ai indique Succès : c’est normal, Zapier accuse réception tout de suite et exécute ses actions ensuite. Consultez l’historique du Zap (Zap History) pour voir l’erreur réelle.

L’agent ne déclenche jamais l’action

• Le visiteur doit en faire la demande : c’est la consigne de Sens Ai pour ce modèle.
• Donnez à l’action un Nom précis et ajoutez une règle de réponse qui décrit quand l’utiliser.
• Vérifiez que l’action est Active et que son connecteur n’est pas en Erreur (page Intégrations).

Voir le contenu réellement envoyé

Le plus simple est un service comme webhook.site ou requestbin.com :

1. créez une adresse jetable ;
2. pointez temporairement le connecteur Sens Ai vers cette adresse ;
3. lancez Tester l’action ;
4. vous voyez exactement le corps { "data": "…" } et les en-têtes que reçoit votre destination (sans collected : le test n’envoie pas les champs à collecter, qui viennent de la conversation).

Pensez à remettre la bonne adresse ensuite.

Bonnes pratiques

• Un connecteur par destination. Plus simple à révoquer en cas de fuite, plus clair à suivre.
• Nommez connecteurs et actions par destination, pas par technologie. Zapier — HubSpot Contacts est plus parlant que Webhook 3.
• Préférez Zapier ou Make pour les vraies API. Vous évitez la limite de l’enveloppe { "data": ... } et profitez de leurs relances et de leur historique.
• Changez vos jetons régulièrement, et après chaque départ d’une personne qui y a eu accès.

Étape suivante

• Tester l’action en conditions réelles : Tester et déboguer une action.
• Gérer vos jetons sans les dupliquer : Connecteurs et authentification.
• Ce qui arrive avec l’action personnalisée : Créer une action personnalisée.