Webhooks #

Les webhooks permettent à Your AI Connector de notifier automatiquement vos autres outils professionnels dès qu’un événement important se produit — création d’un nouveau contact, prise de rendez-vous, réception d’un message. Au lieu de vérifier manuellement les mises à jour, vos systèmes connectés reçoivent une notification instantanée dès que quelque chose se passe.

Que sont les webhooks ? #

Considérez un webhook comme un SMS automatique entre deux applications. Lorsqu’un événement survient dans Your AI Connector (comme l’inscription d’un nouveau contact), la plateforme envoie instantanément une notification à un autre système de votre choix. Vous fournissez une adresse web (appelée « URL de webhook ») où ces notifications doivent être envoyées — celle-ci est généralement fournie par votre CRM, votre plateforme d’automatisation ou votre développeur.

La page Webhooks envoie uniquement des données HORS de Your AI Connector. Les webhooks configurés ici sont unidirectionnels, de Your AI Connector vers vos autres outils. Pour importer un nouveau prospect ou d’autres données (depuis un formulaire de site web, votre CRM ou GoHighLevel), vous avez deux options. Une Automatisation avec le déclencheur Webhook vous fournit une adresse web vers laquelle votre formulaire ou outil peut envoyer des données, et ses étapes peuvent ensuite créer le contact, envoyer un message, et plus encore. Ou bien votre système effectue un appel API, par exemple l’opération Créer un contact, en utilisant votre clé API ; consultez Accès API et Tunnels.

Les webhooks ne sont inclus que dans certains plans. Si votre plan n’inclut pas les webhooks, la page Webhooks n’est pas disponible et aucun événement n’est envoyé. Tout ce que vous avez enregistré précédemment reste sur votre compte et recommencera à être envoyé dès que vous passerez à un plan incluant les webhooks. Les fonctionnalités de votre plan sont listées sur votre page de facturation, et votre fournisseur peut vous indiquer vers quel plan migrer.

Les utilisations courantes incluent :

• Synchroniser les nouveaux contacts avec votre CRM.
• Déclencher un flux de travail dans Zapier, Make ou Pabbly lorsqu’une étiquette est appliquée.
• Avertir votre équipe sur Slack lorsqu’une intervention humaine est requise.
• Mettre à jour votre système de calendrier lorsqu’un rendez-vous est réservé.
• Enregistrer des résumés de conversation dans votre base de données.

Configuration des webhooks #

1. Dans la barre latérale gauche, cliquez sur Paramètres (icône d’engrenage).
2. Dans la barre latérale des paramètres, sous le groupe Intégrations, cliquez sur Webhooks.

Sur un compte où aucun webhook n’est encore configuré, la page ressemble à ceci :

3. Cliquez sur New webhook, en haut à droite. Un formulaire s’ouvre directement sur la page :

4. Remplissez :
   • URL de point de terminaison (Endpoint URL) — l’adresse web vers laquelle Your AI Connector enverra les notifications d’événements. Vous l’obtenez auprès de votre système externe (CRM, plateforme d’automatisation ou serveur personnalisé).
   • Nom — une étiquette que vous reconnaîtrez plus tard (par exemple « Alertes Slack » ou « Synchronisation CRM »). Pour votre référence uniquement.

Votre URL de webhook doit être une adresse https:// accessible publiquement. Les adresses http:// simples, localhost ou les adresses de réseau privé, ainsi que les adresses internes à la plateforme sont rejetées lors de l’enregistrement. Pour tester depuis votre propre machine, utilisez un tunnel public (webhook.site ou ngrok) au lieu de localhost.

5. Sous Événements, cliquez sur les événements que vous souhaitez que ce webhook reçoive — les 24 sont listés dans Les 24 événements de webhook.
6. (Facultatif) Activez Réessayer les livraisons échouées si vous voulez que Your AI Connector continue d’essayer en cas d’échec temporaire — voir Réessayer les livraisons échouées.
7. Cliquez sur Créer un webhook. Il apparaît dans la liste sous le formulaire, et vous pouvez cliquer sur Tester sur sa ligne à tout moment pour envoyer une charge utile (payload) d’exemple à votre point de terminaison.

Autorisation requise. L’ajout, la modification ou le test de webhooks nécessitent l’autorisation « modifier » des Intégrations (les membres de l’équipe en lecture seule voient un avis de lecture seule au lieu du formulaire).

La signature d’un webhook nécessite qu’il soit déjà enregistré au préalable — ouvrez la ligne d’un webhook existant pour le modifier, et le panneau Secret de signature apparaîtra en bas du formulaire de modification. Un brouillon tout neuf et non enregistré n’a pas encore d’option de signature — consultez Charges utiles signées ci-dessous.

Un webhook pour tous vos comptes clients (Agences) #

Si vous gérez une agence, vous n’avez pas besoin de recréer le même webhook sur chaque compte client. Sur le compte d’agence, le formulaire de webhook dispose d’un commutateur supplémentaire : Déclencher également pour tous les comptes clients. Activez-le et ce webhook recevra également les événements qui se produisent sur chaque compte client sous votre agence — un seul point de terminaison pour toute l’agence.

Fonctionnement :

• Le bloc user vous indique à quel client appartient un événement. Chaque notification contient déjà un bloc user identifiant le compte sur lequel l’événement s’est produit, afin que votre automatisation puisse effectuer le routage par client.
• Les paramètres de votre webhook s’appliquent partout. Les événements que vous avez sélectionnés, le secret de signature et le paramètre de réessai sont également utilisés pour les livraisons des comptes clients.
• Pas de double livraison. Si un compte client possède son propre webhook pointant vers la même URL, c’est celui-ci qui est utilisé pour les événements de ce compte — le même événement n’arrive jamais deux fois au même point de terminaison.
• Les clients ne le voient pas. Le webhook n’apparaît pas sur la page Webhooks du compte client, et les clients ne peuvent pas le désactiver — c’est à vous de le gérer.
• La fiabilité est suivie par compte client. Si votre point de terminaison continue d’échouer, il est automatiquement désactivé pour le compte dont les livraisons ont échoué (voir Fiabilité des webhooks), et non pour toute l’agence en une seule fois.

Le commutateur n’apparaît que sur les comptes d’agence. Sa configuration via l’API est également prise en charge — voir le champ apply_to_sub_accounts dans l’API Webhooks.

Événements déclencheurs disponibles #

Vous pouvez activer ou désactiver chacun des 24 événements de webhook indépendamment. Lorsqu’un événement se déclenche, Your AI Connector envoie une notification à votre URL de webhook avec les données pertinentes. Chaque événement, sa signification et le code event qu’il place dans la charge utile sont listés ensemble dans Les 24 événements de webhook plus bas sur cette page.

Bon à savoir : Tâche créée, Tâche mise à jour et Tâche terminée sont entièrement sélectionnables et s’enregistrent correctement. Résumé quotidien créé est également un ajout récent. Voir Webhook de tâche terminée ci-dessous pour la structure de cette charge utile.

Déclencheurs de webhook basés sur les tags #

subscribed_to_tags ne limite pas les événements d’un webhook à une étiquette. Il restreint uniquement les étiquettes qui génèrent une notification de résumé de conversation. Pour recevoir une requête lorsqu’une étiquette spécifique est appliquée, définissez une URL de webhook sur cette étiquette dans l’onglet Étiquettes de l’éditeur d’agent.

Le formulaire de webhook lui-même ne dispose pas de sélecteur de balises, que ce soit lors de la création d’un nouveau webhook ou lors de la modification d’un existant, donc subscribed_to_tags ne peut être lu ou modifié que via l’API Webhooks, ou en demandant au support.

Bon à savoir : la modification d’un webhook existant qui possède une liste subscribed_to_tags (le renommer, changer ses événements, activer/désactiver les tentatives) ne vide plus cette liste — comme le formulaire n’a pas de sélecteur de balises à renvoyer, l’enregistrement depuis cette page laisse désormais la liste existante intacte. (C’était un véritable bug avant le 21 juillet 2026 : l’enregistrement depuis le formulaire de webhook effaçait la liste car il envoyait toujours une liste de balises vide. Si un webhook a perdu sa liste subscribed_to_tags avant cette date, il devra être reconfiguré via l’API.)

Générer un résumé pour les contacts tagués #

Lorsqu’un webhook possède une liste subscribed_to_tags, vous pouvez activer Générer un résumé. Lorsqu’elle est activée, Your AI Connector génère automatiquement un résumé de conversation pour le contact lorsqu’une de ces balises est appliquée, et l’inclut dans les données du webhook — un contexte complet sans requête séparée.

Tester votre webhook #

1. Ouvrez Paramètres → Intégrations → Webhooks.
2. Sur la ligne de votre webhook, cliquez sur Tester.
3. Vérifiez votre système externe pour confirmer qu’il a bien reçu les données de test.
4. Examinez le format des données pour vous assurer que votre système peut les analyser correctement.

Pour un test complet de bout en bout, envoyez un message qui déclencherait l’un de vos événements configurés (une diffusion ou un message entrant sur un canal connecté) et vérifiez que le webhook se déclenche avec les données réelles.

Ce qui constitue une livraison réussie #

Que vous cliquiez sur Test ou que l’événement se déclenche réellement, nous envoyons la même chose :

• Une requête POST (jamais GET), avec le corps au format JSON et Content-Type: application/json.
• Les en-têtes listés sous Charges utiles signées. Les en-têtes de signature ne sont inclus qu’une fois que vous avez défini un secret de signature.

Nous considérons la livraison comme réussie lorsque :

• Votre point de terminaison répond avec n’importe quel statut 2xx (200, 201, 204 — tout est acceptable).
• Il répond dans un délai de 30 secondes.

Quelques points qui surprennent souvent :

• Le corps de la réponse est ignoré. Vous n’avez pas besoin de renvoyer un JSON particulier. Un code 200 vide suffit.
• Les redirections comptent comme un échec. Nous ne les suivons pas, donc un code 301 ou 302 (y compris une redirection de barre oblique finale, ou http vers https) est enregistré comme une livraison échouée. Enregistrez l’URL finale, pas celle qui redirige.
• Les chaînes de requête sont entièrement prises en charge. https://your-app.com/hook?token=abc123 est envoyé exactement tel que vous l’avez enregistré, donc placer un jeton dans la chaîne de requête fonctionne tout aussi bien que de le placer dans le chemin.
• Votre URL doit être https:// et accessible publiquement. Les adresses appartenant à l’infrastructure même de Your AI Connector sont rejetées, mais vos propres points de terminaison sur Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting ou ailleurs sont acceptés.
• Un pare-feu ou une couche de protection contre les bots devant votre point de terminaison peut nous bloquer. Le cas le plus courant est Cloudflare : si votre zone a le mode « Bot Fight » ou un défi géré activé, notre requête reçoit une page de défi « Just a moment… » avec un code 403 au lieu d’atteindre votre serveur — et une requête serveur à serveur ne peut jamais réussir un défi de navigateur, donc le bouton Test et les événements réels échouent de la même manière. Le bouton Test vous indiquera quand cela se produit (« Cloudflare affiche un défi bot à notre requête »). Corrigez cela dans Cloudflare avec une règle de sécurité / WAF qui ignore les défis pour votre chemin de webhook (ou pour l’agent utilisateur Webhook-Delivery/1.0), puis cliquez à nouveau sur Test.
• Si votre pare-feu nécessite une liste d’autorisation IP à la place (par exemple, le plan gratuit de Cloudflare, où le mode « Bot Fight » simple ne peut pas être ignoré par une règle WAF, mais où une règle d’accès IP définie sur Autoriser s’exécute avant), nous pouvons vous aider : chaque livraison, qu’elle provienne du bouton Test ou d’un événement en direct, est envoyée depuis une adresse IPv4 fixe (pas de plages, pas d’IPv6, pas de rotation). Contactez le support et nous vous donnerons l’adresse à ajouter à votre liste d’autorisation. Conservez la vérification de signature comme votre véritable contrôle de confiance, car elle valide chaque charge utile, quelle que soit sa provenance.
• Le résultat du test vous indique exactement ce que votre point de terminaison a répondu. Un test échoué affiche désormais la raison réelle (le statut HTTP renvoyé par votre point de terminaison, un délai d’attente, ou le fait que nous n’avons pas pu atteindre l’adresse du tout) au lieu d’une erreur générique, et un test sur un webhook enregistré est envoyé signé lorsque la signature est activée, exactement comme un événement en direct.

Utiliser n8n, Make ou Zapier (« URL de test » vs « URL de production ») #

Les plateformes d’automatisation fournissent généralement deux adresses de webhook différentes, ce qui prête souvent à confusion :

• Une URL de test (dans n8n, elle contient /webhook-test/). Elle ne reçoit des données que lorsque vous surveillez activement le canevas et que vous venez de cliquer sur Listen for test event (ou Test workflow). Elle capture un seul événement puis arrête l’écoute — donc cliquer sur Test dans Your AI Connector plusieurs fois de suite ne capture que le premier, et seulement si la fenêtre d’écoute est active à ce moment précis. Pour tester : cliquez d’abord sur Listen for test event dans n8n, puis revenez dans Your AI Connector et cliquez une fois sur Test.
• Une URL de production (dans n8n, elle contient /webhook/, sans -test). C’est celle qu’il faut coller dans Your AI Connector pour les événements en direct. Elle ne fonctionne qu’une fois votre workflow passé en mode Actif. Si le workflow n’est pas actif, n8n rejette la requête avec une erreur “404 / webhook not registered”, même si Your AI Connector a envoyé les données correctement.

En résumé : testez avec l’URL de test pendant l’écoute, mais pour que le webhook continue de fonctionner avec des contacts réels, enregistrez l’URL de production dans Your AI Connector et assurez-vous que le workflow est Active.

Format des données du webhook #

Lorsqu’un webhook se déclenche, Your AI Connector envoie des données structurées (JSON) à votre URL de webhook. Si vous utilisez une plateforme d’automatisation comme Zapier ou Make, elle analyse automatiquement ces données pour vous. Si vous créez une intégration personnalisée :

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

Lisez agent, pas campaign. Les campagnes ont été transférées vers les agents IA et les diffusions (voir Les campagnes ont été déplacées), vos contacts sont donc associés à un agent et agent vous indique lequel a géré la conversation. Le champ campaign est toujours envoyé pour que les anciens récepteurs continuent de fonctionner, mais il est généralement null ; il n’est rempli que pour un contact qui conserve un lien vers une campagne classique. Ne supposez pas que campaign est toujours présent.

Le bloc agent est arrivé le 15 août 2026. Il se situe aux côtés de campaign parmi les événements liés à une conversation — une discussion terminée, ne pas déranger, une reprise, une désarchivage, une mise en pause de l’IA, un nouveau message, un résumé de conversation et le webhook que vous pouvez définir sur une étiquette — et contient le id et le name de l’agent traitant, ou null lorsqu’aucun agent n’est impliqué. Il est purement additif : chaque champ que vous recevez déjà reste inchangé, donc un récepteur que vous avez construit avant cette date continuera de fonctionner sans rien avoir à mettre à jour.

Certains événements ajoutent leur propre bloc de niveau supérieur. Par exemple, Rendez-vous réservé, Rendez-vous annulé et Rendez-vous reprogrammé ajoutent un bloc appointment (voir Webhook de rendez-vous réservé), Nouveau message ajoute un bloc message complet avec le texte (voir Webhook de nouveau message), et Livraisons et Lectures ajoutent un court bloc message avec uniquement l’ID et le statut du message (voir Webhook de livraisons et lectures).

Les événements Deliveries et Reads vous indiquent quel message, mais pas son contenu. Ils contiennent un bloc message incluant l’id et le status du message — et cet id est le même messageId que celui renvoyé par le point de terminaison d’envoi de message, vous permettant ainsi de faire correspondre un accusé de réception ou de lecture au message exact que vous avez envoyé — mais sans le corps du message. Replies ne contient aucun bloc message. Si vous avez besoin du texte envoyé ou reçu, abonnez-vous également à New Message.

Deux choses à savoir avant d’écrire votre récepteur. Il n’y a pas de champ timestamp, et pas de wrapper data. Chaque bloc se situe au niveau supérieur de l’objet JSON, comme indiqué ci-dessus.

Les 24 événements de webhook #

Les 24 événements de webhook, avec l’étiquette d’affichage que vous cochez dans l’application et le code event envoyé dans la charge utile. Le code event est une courte chaîne qui ne correspond pas à l’étiquette d’affichage, donc faites correspondre votre récepteur sur le code, pas sur l’étiquette :

Deux autres codes n’apparaissent jamais dans cette liste car vous ne vous y abonnez pas : contact_tags_updated, envoyé par une URL de webhook définie sur une balise individuelle, et summary_generated, envoyé lorsqu’un résumé de chat est écrit pour une balise dans la liste subscribed_to_tags d’un webhook.

L’événement Canal connecté n’est pas encore envoyé. Il apparaît dans la liste des événements, mais rien ne l’émet aujourd’hui. Ne développez rien en vous basant dessus.

Les notifications basées sur les tags et les tâches utilisent leurs propres formes distinctes. Voir Contact Tags Updated et Task Completed.

Webhook de création de contact #

Envoyé lorsque l’événement Contact créé se déclenche (un nouveau contact est ajouté manuellement, via une importation ou via l’API).

Nom de l’événement #

contactCreated

Format de la charge utile #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

L’échantillon « Test » et un événement réel sont légèrement différents. Le bouton de test envoie des données fictives (John Doe, un bloc de campagne échantillon). Un événement de création de contact réel contient les détails réels du contact, et certains champs peuvent être vides selon le canal.

Webhook Nouveau message #

Ce webhook se déclenche à chaque fois qu’un message est ajouté à une conversation, sur n’importe quel canal. Il couvre les deux directions : les messages que votre contact vous envoie, et les messages que votre agent IA, votre équipe ou une diffusion leur envoie. C’est le seul webhook qui inclut le texte du message, c’est donc celui à utiliser lorsque vous souhaitez refléter les conversations dans un système externe.

Nom de l’événement #

new_message

Format de la charge utile #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}

Il n’y a toujours pas de bloc campaign dans cette charge utile. Le nouveau message envoie contact, agent, user et message. Le bloc agent a été ajouté le 15 août 2026 et vous indique quel agent gère la conversation ; si vous avez besoin de plus de contexte sur le contact, recherchez-le via l’API en utilisant contact.id.

Enregistrez les pièces jointes peu après leur réception. Le lien media_url cesse de fonctionner 7 jours après l’arrivée du message, sur tous les canaux (WhatsApp Business API, WhatsApp Web, Instagram, Messenger, Telegram, widget de chat et les autres) ; le fichier lui-même est conservé. Pour obtenir un nouveau lien plus tard, appelez Télécharger la pièce jointe d’un message avec contacts/{contact.id}/messages/{message.id}. Les champs ont été ajoutés le 13 septembre 2026.

Lorsque media_url est null mais que le corps indique qu’un fichier est arrivé. Quelques pièces jointes sont stockées d’une manière qui n’a pas de lien direct, et un reel, une publication ou une mention en story Instagram partagé est un lien vers Instagram, pas un fichier, donc ceux-ci arrivent également en tant que null (le corps nomme ce qui a été partagé). Pour un fichier, appelez Download a message’s attachment avec l’identifiant du message pour obtenir un lien.

L’historique importé ne déclenche pas ce webhook. Lorsqu’un numéro WhatsApp Web importe ses conversations passées, ces anciens messages sont enregistrés sans notification de nouveau message pour chacun d’eux.

Les enregistrements internes de l’IA ne déclenchent pas ce webhook. En plus des messages réels, la plateforme conserve ses propres lignes de comptabilité dans une conversation (les appels d’outils de l’IA et les enregistrements de tours internes). Ceux-ci ne sont jamais envoyés — vous ne recevez que les messages qui ont été réellement envoyés ou reçus.

Webhook Deliveries and Reads #

Ces deux événements signalent ce qui est arrivé à un message après son départ de Your AI Connector : Deliveries se déclenche lorsqu’un message atteint le contact (ou échoue à le faire), et Reads se déclenche lorsque le contact l’ouvre, sur les canaux prenant en charge les accusés de lecture.

Tous deux contiennent un bloc message avec l’ID du message concerné par l’événement, vous permettant de faire correspondre la mise à jour au message exact que vous avez envoyé.

Noms des événements #

delivered et undelivered pour Deliveries, read pour Reads.

Format de la charge utile #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Comment faire correspondre une mise à jour au message que vous avez envoyé. Stockez l’messageId que vous recevez lorsque vous envoyez un message via l’API. Lorsqu’une notification Deliveries ou Reads arrive, recherchez cet ID stocké dans le champ message.id de la charge utile — il s’agit de votre accusé de réception ou de lecture pour ce message précis.

Il n’y a pas de texte de message ici. Le bloc message ne contient que l’ID et le statut. Abonnez-vous à New Message si vous avez également besoin du corps du message.

Le bloc message n’est présent que lorsque nous savons de quel message il s’agit. Dans les rares cas de mise à jour que nous ne pouvons pas relier à un message stocké, le bloc est entièrement omis plutôt que d’être envoyé vide — vérifiez donc que message existe avant de lire message.id.

Une notification par changement de statut. Un seul message sortant produit normalement une notification delivered puis, sur les canaux avec accusés de lecture, une notification read. Un échec d’envoi produit undelivered à la place.

Appointment Booked Webhook #

Se déclenche lorsqu’un contact prend rendez-vous. Il se déclenche de la même manière, que l’IA l’ait réservé pendant une conversation, que vous l’ayez réservé manuellement ou qu’il soit arrivé via l’API.

Nom de l’événement #

booked

Format de la charge utile #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id est souvent null dans ce webhook, et c’est normal. L’événement Google Calendar est créé au moment même où cette notification est envoyée, donc l’identifiant n’est généralement pas encore prêt. Récupérez le rendez-vous par son appointment_id un peu plus tard si vous en avez besoin. Il reste null de façon permanente si aucun Google Calendar n’est connecté au compte, donc ne l’attendez pas indéfiniment.

Le bouton « Tester » envoie un bloc appointment d’exemple avec des valeurs fictives, afin que vous puissiez construire votre intégration en fonction de la structure avant qu’une vraie réservation n’arrive.

Deux cas où ce webhook ne se déclenche pas : les rendez-vous importés depuis un calendrier externe et les réservations effectuées via l’intégration Formitable.

Webhooks de rendez-vous annulé et reprogrammé #

Rendez-vous annulé se déclenche lorsqu’un rendez-vous est annulé, et Rendez-vous reprogrammé se déclenche lorsqu’il est déplacé vers une nouvelle heure de début ou de fin. Les deux se déclenchent de la même manière, que l’IA l’ait fait pendant une conversation, que vous l’ayez modifié dans l’application, qu’il soit arrivé via l’API ou que quelqu’un ait modifié l’événement dans le Google Calendar connecté.

Noms des événements #

appointment_cancelled et appointment_rescheduled

Format de la charge utile #

Le corps est le même que pour Rendez-vous réservé, avec le rendez-vous tel qu’il est après la modification. Une annulation ajoute appointment.cancelation_reason ; une reprogrammation ajoute un bloc previous de niveau supérieur avec les anciennes heures :

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

Un changement, un événement. L’annulation d’un rendez-vous envoie uniquement Rendez-vous annulé, même si son heure a changé lors de la même modification. La modification du titre, des notes ou de la salle uniquement n’envoie rien. Déplacer le même rendez-vous deux fois envoie deux événements Rendez-vous reprogrammé.

Webhook de conversation conclue #

Se déclenche lorsque l’IA décide qu’une conversation a atteint sa fin (une réservation effectuée, un prospect disqualifié, etc.).

Nom de l’événement #

chat_concluded

Format de la charge utile #

La charge utile contient event, le contact complet, l’agent agent qui a géré la discussion et le user du compte. Elle contient également conversation_cost, le coût de cette conversation en crédits, afin qu’un flux n8n ou Make puisse l’enregistrer sans appel supplémentaire :

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits : crédits facturés au cours de cette conversation, remboursements déduits. Il est comptabilisé de la même manière que le rapport des coûts de conversation dans l’API.
• outcome : contained (l’IA l’a géré seule), handed_off (quelqu’un de votre équipe a répondu après l’IA, ou l’IA a alerté un humain) ou no_ai.
• conversation_cost est omis lorsque le chiffre ne peut pas être calculé à ce moment-là. Considérez-le comme facultatif.

Webhook de mise à jour des tags de contact #

Se déclenche lorsqu’une étiquette est appliquée à un contact, et que cette étiquette a une URL de webhook configurée sur l’agent auquel le contact est assigné.

Nom de l’événement #

contact_tags_updated

Quand il est déclenché #

• Une étiquette est appliquée à un contact auquel un agent IA est assigné.
• Au moins l’une des étiquettes appliquées possède une URL de webhook définie dans l’onglet Étiquettes de l’éditeur de cet agent.

Un contact qui porte encore un lien vers une campagne classique datant d’avant le passage aux agents constitue un cas particulier : si les étiquettes de cette campagne comportent des URL de webhook, celles-ci sont utilisées ; sinon, celles de l’agent sont utilisées.

Si plusieurs étiquettes avec des URL de webhook différentes sont appliquées lors de la même mise à jour, une requête est envoyée par URL, chacune ne contenant que les étiquettes associées à cette URL.

La suppression d’une étiquette n’envoie jamais de requête. La plupart des utilisateurs dirigent ces URL vers une action — collecter un acompte, réserver un créneau, alerter un représentant — de sorte qu’une étiquette retirée d’un contact pourrait relancer cette action. Ce n’est plus possible. Une suppression apparaît toujours dans removed_tags lorsqu’elle se produit lors de la même mise à jour qu’une application envoyée à la même URL, afin qu’une automatisation lisant les deux tableaux conserve une vue d’ensemble ; ce qu’elle ne verra jamais, c’est une requête causée par une suppression seule. (Modifié le 12 août 2026. Avant cette date, les suppressions envoyaient également une requête.)

Format de la charge utile #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Tester un webhook de tag #

À côté du champ URL du webhook dans l’onglet Tags, vous trouverez un bouton Tester. Il envoie immédiatement une charge utile (payload) exemple à cette URL, afin que vous puissiez confirmer que votre automatisation la reçoit avant d’attendre une vraie conversation.

Le test envoie la même forme de contact_tags_updated que celle illustrée ci-dessus, en utilisant un contact fictif, avec le tag que vous testez dans added_tags et un removed_tags vide. Ce que votre automatisation voit lors du test est ce qu’elle verra en production.

Deux choses à savoir :

• Enregistrez d’abord la balise. Le test recherche la balise par son nom enregistré, donc une toute nouvelle balise ou un renommage non enregistré ne peut pas encore être testé. Le bouton reste grisé jusqu’à ce que le nom à l’écran corresponde à celui enregistré.
• Un test échoué ne compte pas contre votre webhook. Les tests ne contribuent jamais à la désactivation automatique après des échecs répétés décrite dans Fiabilité des webhooks.

Si le test échoue, le message vous indique ce que votre point de terminaison a répondu (par exemple un 404 ou un 500), ce qui suffit généralement à identifier une URL incorrecte ou un workflow qui n’est pas activé.

Webhook de tâche terminée #

Pour référence uniquement. Les webhooks de tâches (en tant que données) sont documentés ici pour les développeurs ; les événements Tâche créée, Tâche mise à jour et Tâche terminée sont sélectionnables dans la liste d’événements standard sur le formulaire de webhook comme n’importe quel autre événement — voir Événements déclencheurs disponibles et Les 24 événements de webhook.

Cette charge utile est envoyée lorsqu’une tâche passe dans une étape marquée comme étape de finalisation. Une tâche se déplaçant entre des étapes autres que de finalisation envoie la forme taskUpdated à la place.

Nom de l’événement #

taskCompleted

Quand il est déclenché #

• Une tâche est mise à jour.
• Sa valeur stage a changé par rapport à sa valeur précédente.
• La nouvelle étape est configurée comme une étape de finalisation dans les paramètres d’étape de tâche du compte.

Format de la charge utile #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Désactiver (ou supprimer) un webhook #

Chaque webhook dispose d’un interrupteur marche/arrêt, directement sur sa ligne. Le désactiver (off) empêche la réception d’événements, mais conserve tout ce que vous avez configuré — l’URL, les événements, toute clé secrète de signature. Réactivez-le et il reprendra là où il s’était arrêté ; rien de ce qui s’est passé pendant qu’il était désactivé ne sera transmis ultérieurement.

Utilisez cette option lorsque vous souhaitez interrompre les envois pendant un certain temps : votre point de terminaison est en cours de reconstruction, vous déboguez une intégration trop bavarde ou vous mettez en pause une automatisation.

Supprimer un webhook (l’icône de corbeille sur sa ligne) le supprime définitivement, y compris sa clé secrète de signature. Si vous souhaitez simplement arrêter les livraisons, désactivez-le plutôt — la suppression est destinée au moment où vous n’utilisez plus du tout le point de terminaison.

Ceci n’est pas la même chose qu’un webhook désactivé automatiquement. Si nous désactivons votre webhook après des échecs répétés (voir Fiabilité des webhooks), le bouton ci-dessus ne le réactivera pas. Une fois votre point de terminaison corrigé, modifiez le webhook et enregistrez-le avec une URL différente (tout changement d’URL le réactive), ou appelez le point de terminaison de réactivation via l’API — ou demandez au support de le réactiver pour vous.

Charges utiles signées (Vérifier qu’un webhook provient bien de nous) #

Quiconque découvre l’URL de votre webhook pourrait lui envoyer une fausse requête. Si vous agissez automatiquement sur les webhooks — mise à jour de la facturation, création d’enregistrements CRM — l’activation de la signature vous permet de vérifier que chaque requête provient bien de nous.

La signature est facultative et désactivée par défaut, et vous l’activez par webhook, depuis la vue d’édition de ce webhook (ouvrez la ligne d’un webhook enregistré).

Activer la signature #

1. Ouvrez le webhook (Paramètres → Intégrations → Webhooks → cliquez sur la ligne de votre webhook).
2. Dans la section Clé secrète de signature, cliquez sur Générer.
3. Copiez la clé secrète (elle commence par whsec_) et stockez-la dans votre système de réception. Traitez-la comme un mot de passe.

Vous pouvez revenir pour révéler, copier, renouveler ou désactiver la clé secrète à tout moment depuis ce même panneau.

Ce que nous envoyons #

Une fois la signature activée, chaque livraison pour ce webhook comporte ces deux en-têtes HTTP supplémentaires :

Ces trois éléments sont présents sur chaque livraison, signée ou non :

Comment vérifier #

La signature est un HMAC-SHA256 de la chaîne <timestamp>.<raw request body>, utilisant votre secret de signature comme clé.

Vérifiez par rapport au corps de la requête brute — les octets exacts que vous avez reçus. Si votre framework analyse le JSON et le resérialise avant vérification, les octets peuvent changer et la signature ne correspondra pas.

Exemple Node.js :

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Exemple Python :

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Comparez les signatures avec une fonction sécurisée contre les attaques temporelles (timingSafeEqual / compare_digest), et non ==. Cela ne coûte rien et permet d’éviter une classe subtile d’attaques.

Rotation du secret #

Cliquez sur Rotation pour remplacer le secret. Le changement est immédiat : la livraison suivante est signée uniquement avec le nouveau secret. Si votre point de terminaison est en ligne, acceptez à la fois l’ancien et le nouveau secret pendant quelques minutes, le temps de déployer le nouveau.

Désactiver la signature arrête simplement l’envoi des en-têtes de signature.

Réessayer les livraisons échouées #

Par défaut, une livraison qui échoue n’est pas réessayée — si votre système est hors ligne à ce moment-là, cet événement est perdu.

Activez Réessayer les livraisons échouées sur un webhook (dans le formulaire de création/modification) et nous continuerons d’essayer :

Cela couvre environ 2 heures et 40 minutes, ce qui permet à un webhook de survivre à une fenêtre de maintenance ou à une courte interruption de votre côté.

Ce qui est réessayé : les problèmes temporaires — votre serveur renvoyant une erreur 5xx, un délai d’attente (timeout) ou un échec de connexion.

Ce qui ne fonctionne pas : si votre point de terminaison rejette lui-même la requête (toute erreur 4xx), nous ne réessayons pas — renvoyer la même requête ne produirait que le même rejet.

Quels événements sont réessayés : chaque événement, depuis le 24 septembre 2026. Cela couvre les webhooks de tags (contact_tags_updated), les trois événements de tâche, le résumé quotidien, le webhook de résumé, Nouveau message, Chat terminé, Contact mis en pause, Contact repris, Contact ne pas déranger, Contact désarchivé, Solde de crédits faible, les événements de diffusion, ainsi que les événements de contact et d’activité : Contact créé, Rendez-vous réservé, Humain alerté, Réponses, Lectures, Livraisons, Crédits dépensés et Crédits rechargés. Avant cette date, Nouveau message, Chat terminé, Contact mis en pause, Contact repris, Contact ne pas déranger, Contact désarchivé et le webhook de résumé étaient envoyés une seule fois, indépendamment du commutateur. Chaque événement comporte X-Webhook-Delivery, donc une seule règle de dédoublonnage les couvre tous.

Activez les tentatives de nouvelle livraison uniquement si votre point de terminaison est idempotent. Les tentatives signifient qu’un même événement peut arriver plusieurs fois. Utilisez l’en-tête X-Webhook-Delivery pour reconnaître une répétition : il reste identique pour chaque tentative d’un même événement, vous pouvez donc ignorer en toute sécurité un identifiant que vous avez déjà traité.

Les tentatives de nouvelle tentative interagissent avec la désactivation automatique après des échecs répétés (voir Fiabilité des webhooks) comme vous le souhaiteriez : le compteur d’échecs comptabilise une livraison complète, uniquement après que chaque nouvelle tentative a été épuisée — et non chaque tentative individuelle.

Fiabilité des webhooks #

• Your AI Connector envoie des webhooks via une connexion sécurisée (HTTPS). Assurez-vous que l’adresse web que vous fournissez utilise HTTPS.
• Si votre système renvoie une erreur, la livraison est considérée comme ayant échoué.
• Surveillez la disponibilité de votre système de réception pour éviter de manquer des événements.
• Pour les flux de travail critiques, activez Réessayer les livraisons échouées et envisagez également un mécanisme de secours.

Les webhooks sont désactivés automatiquement après des échecs répétés. Si l’URL de votre webhook échoue de manière répétée (environ 5 erreurs consécutives, ou 3 erreurs consécutives pour des erreurs de configuration), Your AI Connector arrête automatiquement d’envoyer des événements à cette URL. Pour le réactiver une fois que votre point de terminaison est opérationnel : modifiez le webhook et enregistrez-le avec une URL différente (tout changement d’URL le réactive), ou utilisez le point de terminaison de réactivation via l’API — enregistrer à nouveau avec la même URL ne suffit pas. Le support peut également le réactiver pour vous.

Dépannage #

Étapes suivantes #

• Intégration GoHighLevel — utilisez des webhooks pour intégrer Your AI Connector avec GHL.
• Accès API — combinez les webhooks avec l’API pour des automatisations puissantes.
• Utiliser des étiquettes pour classer les contacts — configurez des étiquettes qui déclenchent vos webhooks.