Bloc Webhook - Recevez des appels HTTP entrants dans le flux de votre chatbot

Mettez en pause le flux de votre chatbot ChatMaxima et attendez un appel HTTP externe. Recevez des charges utiles, reprenez le flux et renvoyez des réponses HTTP personnalisées à l'appelant.

Vue d'ensemble

Le bloc Webhook permet à un système externe d'appeler votre chatbot par HTTP. Il peut être utilisé de deux façons : comme premier bloc d'un flux (le webhook lui-même démarre la conversation), ou comme bloc en cours de flux qui met la conversation en pause et attend un rappel externe pour la reprendre. Dans les deux cas, la charge utile entrante est analysée et mise à disposition des blocs en aval sous forme de variables. Vous pouvez éventuellement renvoyer une réponse HTTP personnalisée à l'appelant avec le bloc Réponse de webhook.

C'est l'inverse du bloc API. Le bloc API envoie des requêtes sortantes. Le bloc Webhook écoute les requêtes entrantes. Les cas d'usage typiques incluent le démarrage d'une nouvelle conversation à partir d'un événement externe (une soumission de formulaire, la création d'un enregistrement CRM, un déclencheur iPaaS comme n8n ou Zapier), l'attente d'un rappel de passerelle de paiement, la réception d'une confirmation de livraison d'OTP d'un fournisseur SMS tiers, la notification de la fin d'une tâche backend de longue durée, ou l'acceptation de mises à jour asynchrones d'une application externe.

Bloc Webhook vs bloc API

Aspect	Bloc API	Bloc Webhook
Direction	Sortant (le bot appelle l'API)	Entrant (un système externe appelle le bot)
Déclencheur	Automatique quand le flux atteint le bloc	Un POST HTTP externe démarre ou reprend le flux
Placement	En cours de flux uniquement	Premier bloc ou en cours de flux
Comportement d'attente	Synchrone, délai de 30 secondes	Démarre le flux à l'arrivée, ou met le flux en pause jusqu'à l'arrivée de l'appel
Usage typique	Rechercher des données, pousser des mises à jour	Démarrer des conversations à partir d'événements externes, attendre des rappels asynchrones
Gestion de la réponse	Analyse le corps de la réponse vers des variables	La charge utile entrante devient des variables

Où le trouver

Ouvrez votre chatbot dans Studio
Faites glisser le bloc Webhook depuis la barre latérale gauche vers le canevas
Placez-le comme premier bloc de votre flux (pour démarrer une conversation à partir d'un événement externe) ou connectez-le après n'importe quel bloc précédent (pour mettre en pause et attendre un rappel en cours de flux)
Double-cliquez sur le bloc pour le configurer

Pour renvoyer une réponse HTTP personnalisée à l'appelant, ajoutez un bloc Réponse de webhook immédiatement après le bloc Webhook.

Webhook comme premier bloc

Lorsque le bloc Webhook est le premier bloc du flux, il n'y a pas encore de conversation active. Le POST externe crée la conversation, analyse la charge utile vers des variables et démarre le flux depuis le tout début. C'est le schéma à utiliser lorsque :

Un nouveau lead est créé dans votre CRM et vous voulez que le bot le contacte
Un formulaire est soumis sur votre site web et vous voulez que le bot fasse le suivi
Un workflow n8n, Zapier ou Make déclenche une nouvelle session de discussion
Un événement backend (commande passée, ticket de support ouvert) doit initier une conversation de bot

Webhook en cours de flux

Lorsque le bloc Webhook est placé après un autre bloc, le flux se met en pause à ce point jusqu'à l'arrivée du POST externe. C'est le schéma à utiliser lorsque vous devez transférer à un système externe, attendre sa réponse asynchrone, puis continuer le flux selon ce qu'il a renvoyé.

Comment ça fonctionne

Mode premier bloc

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Mode en cours de flux

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

En mode en cours de flux, le bot stocke la position du bloc actuel lorsqu'il se met en pause. Lorsque le POST externe arrive à l'URL du webhook, le système le fait correspondre à la conversation en pause, reprend à partir de ce bloc et continue en aval.

Configuration

Étape 1 : Placez le bloc Webhook dans le flux

Faites glisser le bloc sur le canevas au point où le flux doit démarrer ou attendre un événement externe. Par exemple :

Comme premier bloc, pour laisser un CRM, un formulaire ou un outil iPaaS démarrer une nouvelle conversation de discussion
Après avoir capturé les détails de paiement, pour attendre la confirmation de la passerelle de paiement
Après avoir déclenché une tâche backend via un bloc API, pour attendre la notification de fin de tâche

Étape 2 : Copiez l'URL du webhook

Chaque bloc Webhook expose une URL unique affichée dans la configuration du bloc. Le format est :

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

Transmettez cette URL au système externe comme destination de sa requête POST. Pour les outils iPaaS (n8n, Zapier, Make), vous la collez dans l'étape HTTP. Pour les CRM et générateurs de formulaires, configurez-la comme webhook sortant dans leur tableau de bord. Pour les passerelles de paiement et backends asynchrones, définissez-la comme URL de rappel au lancement du travail.

Étape 3 : Authentifiez l'appelant

L'URL du webhook accepte un jeton Bearer dans l'en-tête Authorization. Utilisez le jeton affiché dans la configuration du bloc afin que le webhook n'accepte que les appels de systèmes auxquels vous faites confiance.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

Forme de la charge utile

Champ	Objectif
`type`	Type d'événement, généralement `Conversation` pour démarrer ou reprendre une discussion
`channel`	Canal que la conversation doit utiliser (ex. `whatsapp`, `website`). Laissez vide pour utiliser le canal par défaut
`account_alias`	Alias d'équipe lorsque le bot est partagé entre plusieurs comptes
`reference_id`	Identifiant externe que vous pouvez utiliser pour relier la conversation à un enregistrement de votre système
`data`	Objet contenant tous les champs que vous voulez passer comme variables (ex. `name`, `email`, `phone`, champs personnalisés)

Étape 4 : Référencez les champs de la charge utile entrante

Lorsque le POST arrive, l'objet data est analysé et chaque champ devient une variable disponible pour tous les blocs en aval.

Pour une charge utile comme :

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

Vous pouvez référencer :

{name} pour Priya
{phone} pour +919000000000
{order_id} pour ORDER-9981
{customer.email} pour les champs imbriqués
{reference_id} pour les métadonnées de premier niveau

Étape 5 : Soumettez et enregistrez

Cliquez sur Soumettre dans la fenêtre du bloc, puis enregistrez le flux avec Enregistrer les modifications dans la barre supérieure.

Bloc Réponse de webhook

Associez le bloc Webhook à un bloc Réponse de webhook lorsque l'appelant attend une réponse HTTP spécifique. Sans le bloc de réponse, le bot renvoie un 200 OK par défaut avec {"status":"success"}.

Le bloc Réponse de webhook vous permet de personnaliser le code de statut (ex. 201, 400, 500), le type de contenu (application/json, application/xml, text/plain, text/html) et le corps de réponse renvoyé à l'appelant. Vous pouvez insérer des variables de flux avec la syntaxe {variable_name}.

Schémas courants :

Renvoyer 201 Created avec le nouveau {conversation_id} pour les outils iPaaS
Renvoyer 400 avec un champ d'erreur quand la charge utile est invalide
Renvoyer text/plain OK pour les rappels de livraison SMS
Renvoyer du XML pour les intégrations SOAP héritées

Consultez la documentation complète du bloc Réponse de webhook pour les options de configuration, des exemples et le dépannage.

Bonnes pratiques

Validez toujours les charges utiles entrantes. Utilisez un bloc Condition après le bloc Webhook pour vérifier des champs comme status == "success" avant de poursuivre
Utilisez le bloc Réponse de webhook lorsque l'appelant (passerelle de paiement, fournisseur SMS, etc.) attend un format d'accusé de réception spécifique. Sans lui, l'appelant reçoit un 200 OK générique
Définissez un délai significatif ailleurs. Le bloc Webhook lui-même n'expire pas, combinez-le donc avec le Délai d'inactivité pour éviter des flux qui restent en pause indéfiniment
Sécurisez l'URL du webhook. Le jeton dans l'URL est unique par conversation. N'exposez pas l'URL publiquement et ne la journalisez pas dans des systèmes que l'utilisateur peut lire
Gérez le cas d'échec. Branchez le flux selon la charge utile entrante. Si l'événement externe indique un échec, envoyez un message de récupération ou acheminez vers un agent

Cas d'usage courants

Un lead CRM crée une conversation (premier bloc)

Un nouveau lead est ajouté dans votre CRM, et le bot ouvre une conversation WhatsApp pour le qualifier.

Bloc Webhook (premier bloc) : Le CRM POST la charge utile du lead avec phone, name, source
Bloc Message : Hi {name}, thanks for your interest!
Bloc Question : Posez des questions de qualification
Bloc API : Repoussez les données qualifiées vers le CRM

Déclencheur n8n ou Zapier (premier bloc)

Un outil d'automatisation déclenche un webhook lorsqu'un événement spécifique se produit (nouvelle commande Shopify, soumission Typeform, etc.), et le bot fait le suivi avec le client.

Bloc Webhook (premier bloc) : n8n POST {"phone":"...", "order_id":"..."}
Bloc Message : Your order {order_id} has shipped!

Rappel de passerelle de paiement

L'utilisateur initie un paiement, le bot l'envoie vers une page de paiement, puis attend que la passerelle POST le résultat.

Bloc API : Créez une session de paiement, stockez payment_url
Bloc Message : Envoyez payment_url à l'utilisateur
Bloc Webhook : Mettez le flux en pause, passez l'URL du webhook à la passerelle comme rappel
Bloc Condition : Branchez sur {status} == "success"
Bloc Réponse de webhook : Renvoyez {"received":true} à la passerelle

Notification de tâche asynchrone

Le bot déclenche une tâche de génération de rapport de longue durée, attend l'achèvement, puis envoie le lien du rapport à l'utilisateur.

Bloc API : Soumettez la tâche, stockez job_id, incluez l'URL du webhook comme rappel
Bloc Message : « Génération de votre rapport, cela peut prendre une minute... »
Bloc Webhook : Attendez le rappel de fin de tâche
Bloc Message : Your report is ready: {report_url}

Statut de livraison d'OTP tiers

Le bot envoie un OTP via un fournisseur SMS externe qui utilise des webhooks pour confirmer la livraison.

Bloc API : Déclenchez l'envoi de l'OTP, passez l'URL du webhook
Bloc Webhook : Attendez le statut de livraison
Bloc Condition : Branchez sur {delivery_status}
Bloc Message : Demandez le code OTP ou présentez vos excuses pour l'échec de livraison

Soumission de formulaire externe

Une application web distincte collecte des informations supplémentaires et les POST au bot lorsque l'utilisateur termine.

Bloc Message : Envoyez l'URL du formulaire à l'utilisateur
Bloc Webhook : Attendez la soumission du formulaire
Bloc Message : Thanks, we received your {form_field}

Dépannage

Le flux est bloqué sur le bloc Webhook (en cours de flux)

Confirmez que le système externe a réellement effectué un POST vers l'URL du webhook. Vérifiez ses journaux de livraison
Vérifiez que l'URL est accessible depuis le système externe (non bloquée par un pare-feu ou une liste blanche d'IP)
Assurez-vous que l'URL inclut le chemin complet et le jeton final
Combinez avec le Délai d'inactivité pour fermer automatiquement les conversations qui ne reçoivent jamais le rappel

Le webhook de premier bloc ne démarre pas de conversation

Confirmez que le bloc Webhook est bien le tout premier bloc du flux (aucun autre bloc ne s'y connecte)
Vérifiez que la charge utile inclut un identifiant de destinataire (téléphone, e-mail ou ID de visiteur) que le bot peut utiliser pour créer la conversation
Vérifiez que le bot est publié et que le canal (WhatsApp, widget de site web, etc.) est connecté
Inspectez le statut de réponse renvoyé à l'appelant. Un 4xx indique que la charge utile a été rejetée

Les champs de la charge utile entrante sont vides dans les blocs en aval

Confirmez que le Content-Type du POST entrant est application/json ou un type de formulaire pris en charge
Vérifiez les noms de champ exacts dans la charge utile. Les noms de variables sont sensibles à la casse
Pour les champs imbriqués, utilisez la notation par points : {customer.email}, pas {customer_email}
Inspectez la charge utile entrante brute dans le journal de conversation pour voir ce qui a réellement été reçu

L'appelant reçoit un `200 OK` générique au lieu de ma réponse personnalisée

Assurez-vous d'avoir ajouté un bloc Réponse de webhook après le bloc Webhook
Vérifiez que le bloc de réponse est accessible dans le graphe du flux. Un bloc Condition peut le contourner
Vérifiez bien que le bouton Soumettre a été cliqué et que le flux a été enregistré

Le système externe rejette la réponse du webhook

Confirmez que le Content-Type correspond à ce que l'appelant attend (par exemple, application/json vs text/plain)
Validez que le corps de la réponse est bien formé. Un objet JSON non fermé fera réessayer les appelants stricts
Vérifiez le code de statut HTTP. Certains appelants n'acceptent que 200, pas 201 ou 202

Plusieurs POST arrivent pour la même conversation

Certains systèmes externes réessaient les webhooks s'ils pensent que la première livraison a échoué. L'URL du webhook est idempotente par conversation, donc seul le premier POST valide reprend le flux. Les POST suivants reçoivent la réponse configurée sans faire avancer le flux à nouveau.

Étapes suivantes

Bloc Réponse de webhook - Renvoyez des réponses HTTP personnalisées à l'appelant
Bloc API - Appelez des API externes depuis le flux
Délai d'inactivité - Fermez automatiquement les conversations qui restent en pause trop longtemps
Bloc Fin de conversation - Terminez manuellement les conversations avec un bouton de redémarrage
Vue d'ensemble de Studio - Explorez tous les types de blocs et les fonctionnalités du générateur de flux