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.

Les webhooks envoient uniquement des données HORS de Your AI Connector. Un webhook est une voie à sens unique depuis Your AI Connector vers vos autres outils. Il n’existe aucune URL de webhook qui envoie des prospects, des contacts ou des messages DANS la plateforme. Pour intégrer un nouveau prospect — depuis un formulaire de site web, votre CRM ou GoHighLevel — votre système effectue plutôt un appel API. Consultez Accès API (l’opération Créer un contact) et Tunnels. La seule chose dont vous avez besoin pour la direction entrante est votre clé API, qui se trouve dans sa propre section — consultez Accès API. La page Webhooks décrite ici est exclusivement destinée à la direction sortante.

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 22 sont listés dans Les 22 événements de webhook.
6. (Optionnel) 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 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 22 é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 22 é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 balise. Il restreint uniquement les balises qui produisent une notification de résumé de conversation. Pour obtenir une requête lorsqu’une balise spécifique est appliquée, définissez une URL de webhook sur cette balise dans l’onglet Balises de l’agent (ou de la campagne).

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" }
}

campaign ou agent — généralement l’un ou l’autre, pas les deux. Si votre compte utilise des agents, vos contacts sont associés à un agent plutôt qu’à une campagne, donc campaign arrive sous la forme null et agent vous indique lequel l’a traité. Les anciens comptes basés sur les campagnes voient l’inverse. Lisez celui qui est renseigné ; 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, Appointment Booked ajoute un bloc appointment (voir Webhook Appointment Booked), New Message ajoute un bloc message complet avec le texte (voir Webhook New Message), et Deliveries et Reads ajoutent un court bloc message contenant uniquement l’ID et le statut du message (voir Webhook Deliveries and Reads).

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 22 événements de webhook #

Les 22 é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
  },
  "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, une campagne exemple). Un événement réel de création de contact 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 IA, votre équipe ou une campagne lui 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
  },
  "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"
  }
}

Il n’y a toujours pas de bloc campaign dans cette charge utile. New 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 également besoin du contexte de la campagne, recherchez le contact via l’API en utilisant contact.id.

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
  },
  "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,
    "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 “Test” n’inclut pas le bloc appointment. Utilisez-le pour confirmer que votre point de terminaison répond, puis effectuez une vraie réservation pour voir la charge utile complète.

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.

Webhook de mise à jour des tags de contact #

Se déclenche lorsqu’une étiquette est appliquée à un contact, et que cette étiquette possède une URL de webhook configurée sur l’agent ou la campagne auquel le contact appartient.

Nom de l’événement #

contact_tags_updated

Quand il est déclenché #

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

Si le contact possède les deux et que les étiquettes de la campagne comportent des URL de webhook, ce sont celles-ci qui sont prioritaires ; 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"
    }
  },
  "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 standard des événements sur le formulaire de webhook comme tout autre événement — voir Événements déclencheurs disponibles et Les 22 é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 renvoyés en cas d’échec : les webhooks d’étiquettes (contact_tags_updated), les trois événements de tâche et le résumé quotidien. Les autres sont envoyés une seule fois, donc pour ceux-ci, l’option n’a aucun effet. Chaque événement comporte toujours X-Webhook-Delivery, une seule règle de déduplication suffit donc pour 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.