Bloc Réponse de webhook - Renvoyez des réponses HTTP personnalisées aux appelants de webhook

Renvoyez des réponses JSON, XML ou texte brut personnalisées au système qui a déclenché votre webhook ChatMaxima. Configurez le code de statut, le type de contenu et le corps.

Vue d'ensemble

Le bloc Réponse de webhook vous permet de renvoyer une réponse HTTP personnalisée à tout système ayant appelé votre bloc Webhook. Sans ce bloc, ChatMaxima répond avec un 200 OK générique et un corps {"status":"success"}. C'est suffisant pour la plupart des rappels, mais certaines intégrations attendent une forme, un code de statut ou un type de contenu spécifiques avant de considérer la livraison comme réussie.

Utilisez le bloc Réponse de webhook lorsque l'appelant est strict quant à la réponse : passerelles de paiement qui réessaient à moins de voir un champ JSON particulier, systèmes SOAP hérités qui attendent du XML, outils iPaaS qui analysent la réponse dans les étapes suivantes, ou générateurs de formulaires qui affichent la réponse à l'utilisateur.

Bloc Webhook vs bloc Réponse de webhook

Aspect	Bloc Webhook	Bloc Réponse de webhook
Direction	Reçoit un appel HTTP entrant	Renvoie une réponse HTTP à l'appelant
Placement	Premier bloc ou en cours de flux	N'importe où en aval d'un bloc Webhook
Requis	Oui (pour accepter les appels externes)	Facultatif (un `200 OK` par défaut est envoyé si omis)
Objectif	Déclencher ou reprendre le flux	Façonner la réponse HTTP à l'appelant

Où le trouver

Ouvrez votre chatbot dans Studio
Faites glisser le bloc Réponse de webhook depuis la barre latérale gauche vers le canevas
Connectez-le en aval du bloc Webhook qui a reçu la requête
Double-cliquez sur le bloc pour le configurer

Le bloc Réponse de webhook n'a pas besoin d'être le bloc immédiatement suivant. Vous pouvez placer des blocs Condition, API, Définir une variable et Message entre le bloc Webhook et le bloc Réponse de webhook. Lorsque le bloc de réponse est atteint pendant l'exécution du flux, sa configuration devient la réponse HTTP à l'appelant d'origine.

Configuration

Étape 1 : Définissez le code de statut HTTP

Code de statut	À utiliser quand
`200`	Par défaut. Indique le succès à la plupart des appelants
`201`	Utile lorsque le webhook a créé une ressource (ex. une nouvelle conversation)
`202`	Accepté pour un traitement asynchrone (le bot agira dessus plus tard)
`400`	Rejeter les charges utiles malformées
`401`	Rejeter les appelants non autorisés
`500`	Indiquer une défaillance côté bot pour la logique de nouvelle tentative

Étape 2 : Définissez le Content-Type

Content-Type	À utiliser quand
`application/json`	La plupart des intégrations modernes (par défaut)
`application/xml`	Appelants de style SOAP hérité
`text/plain`	Rappels de type vérification d'état
`text/html`	Accusés de réception de soumission de formulaire affichés à un utilisateur

Étape 3 : Rédigez le corps de la réponse

Le corps est un champ texte libre. Rédigez la charge utile exacte que vous voulez renvoyer à l'appelant. Les variables capturées plus tôt dans le flux peuvent être insérées avec la syntaxe {variable_name} (accolades simples).

Pour JSON :

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

Pour XML :

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

Pour le texte brut :

OK

Étape 4 : 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.

Comment ça fonctionne

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

La réponse HTTP est envoyée de manière synchrone : l'appelant externe reste connecté jusqu'à ce que le bloc de réponse soit atteint. Pour cette raison, gardez le chemin entre le bloc Webhook et le bloc Réponse de webhook rapide. Évitez les appels API de longue durée ou la logique chronophage avant le bloc de réponse, sinon l'appelant peut expirer.

Cas d'usage courants

Accuser réception avec l'ID de conversation

Un outil iPaaS (n8n, Zapier, Make) veut enregistrer l'ID de conversation dans son propre système après avoir déclenché le webhook.

Code de statut : 201
Content-Type : application/json
Corps :

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

Renvoyer le résultat de validation

Un générateur de formulaires poste une saisie utilisateur. Le bot la valide et renvoie un succès/échec afin que le formulaire puisse afficher le bon message.

Code de statut : 200
Content-Type : application/json
Corps :

{
  "valid": true,
  "message": "Your request has been received"
}

Rejeter les charges utiles invalides

Combinez un bloc Condition (vérifiant les champs requis) avec un bloc Réponse de webhook sur la branche d'échec qui renvoie 400.

Code de statut : 400
Content-Type : application/json
Corps :

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

Confirmation de passerelle de paiement

Une passerelle de paiement poste un webhook settle. Le bot doit renvoyer une forme JSON spécifique sinon la passerelle continuera de réessayer.

Code de statut : 200
Content-Type : application/json
Corps :

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

Accusé de réception de livraison SMS

Un fournisseur SMS hérité attend une réponse OK en texte brut.

Code de statut : 200
Content-Type : text/plain
Corps : OK

Bonnes pratiques

Gardez le chemin court. Ne placez des blocs entre le Webhook et la Réponse de webhook que s'ils s'exécutent rapidement. Les longs appels API devraient se trouver après le bloc de réponse afin que l'appelant n'expire pas
Répondez toujours rapidement aux appelants qui réessaient. Les passerelles de paiement et les fournisseurs SMS réessaient souvent en quelques secondes. Atteindre le bloc de réponse en une à deux secondes évite les notifications en double
Correspondez exactement à la forme attendue par l'appelant. Les appelants stricts rejettent les réponses même quand le code de statut est correct. Lisez la documentation de l'intégration et testez avec leurs requêtes d'exemple
Utilisez des blocs Condition pour brancher la réponse. Ayez un bloc Réponse de webhook sur la branche de succès et un autre (avec 400 ou 401) sur la branche d'échec
Incluez l'ID de conversation ou de référence. Cela facilite la corrélation entre les journaux de l'appelant et la conversation dans ChatMaxima
Ne mettez pas de données sensibles dans la réponse. La réponse est visible par l'appelant. Ne renvoyez que ce dont il a besoin pour confirmer la réception

Dépannage

L'appelant reçoit le `200 OK` par défaut au lieu de ma réponse personnalisée

Confirmez qu'un bloc Réponse de webhook est présent et accessible depuis le bloc Webhook
Vérifiez le graphe du flux : si une Condition contourne le bloc de réponse, la valeur par défaut est utilisée
Assurez-vous que le bloc a été enregistré. Cliquez sur Soumettre dans la fenêtre, puis sur Enregistrer les modifications dans la barre supérieure

L'appelant réessaie de façon répétée

Assurez-vous que le code de statut correspond à ce que l'appelant considère comme un succès. Certains fournisseurs n'acceptent que 200, pas 201 ou 202
Vérifiez que le corps de la réponse correspond à la forme attendue par l'appelant. Inspectez sa documentation ou ses journaux
Vérifiez s'il y a des blocs en amont entre le Webhook et la Réponse de webhook qui sont lents. L'appelant peut expirer avant l'envoi de la réponse

Les variables apparaissent comme `{variable_name}` brut dans le corps de la réponse

Confirmez que la variable a été définie par un bloc antérieur dans le même flux
Les noms de variables sont sensibles à la casse. Vérifiez l'orthographe
Pour les champs imbriqués, utilisez la notation par points : {customer.email}, pas {customer_email}
Si la variable provient de la charge utile entrante du webhook, assurez-vous que la charge utile contenait réellement le champ

Le JSON malformé est rejeté par les appelants stricts

Validez le modèle de corps en tant que JSON avant d'enregistrer. Une variable non entre guillemets dans un champ chaîne produira un JSON invalide si la valeur contient des guillemets ou des sauts de ligne
Pour les champs numériques comme {amount}, ne les entourez pas de guillemets. Pour les champs chaîne, entourez-les toujours : "name": "{name}"
Testez avec un appel d'exemple (avec curl ou Postman) pour voir les octets réellement renvoyés

Incohérence de Content-Type

Certains appelants exigent explicitement application/json; charset=utf-8. La valeur par défaut envoie application/json sans le charset
Les clients SOAP peuvent exiger text/xml plutôt que application/xml. Vérifiez la documentation de l'intégration

Étapes suivantes

Bloc Webhook - Recevez des appels HTTP entrants pour déclencher ou reprendre un flux
Bloc API - Appelez des API externes depuis le flux
Vue d'ensemble de Studio - Explorez tous les types de blocs et les fonctionnalités du générateur de flux