Intégration Webhooks

Les webhooks vous permettent de connecter Attlas Chat à votre backend, CRM ou outils externes en temps réel. Chaque fois qu’un visiteur interagit avec votre chat, par exemple en laissant ses coordonnées ou en planifiant un rendez-vous, Attlas envoie une requête HTTP POST automatisée à votre endpoint spécifié.

Événements clés

Attlas déclenche des webhooks pour quatre événements principaux :

Événement	Type	Déclenché lorsque
`contact_created`	`contact`	Un nouveau prospect ou contact est créé via une conversation ou une réservation.
`contact_updated`	`contact`	Le profil ou les coordonnées d’un contact existant sont mis à jour lors d’un nouveau contact.
`event_created`	`calendar`	Un visiteur planifie un nouveau rendez-vous sur Google Agenda via le chat.
`event_canceled`	`calendar`	Un rendez-vous planifié est annulé par vous ou par le visiteur.

contact_created est envoyé uniquement lorsqu’un nouveau contact est créé. Si un visiteur récurrent est reconnu grâce à la déduplication (e-mail, téléphone ou historique de conversation), Attlas émet contact_updated à la place.

Comment configurer les Webhooks

La configuration d’un endpoint webhook prend moins d’une minute :

Accédez à vos Paramètres du chat.
Sélectionnez l’onglet Intégrations.
Repérez la carte Webhooks et cliquez sur Connecter.
Saisissez l’URL du Webhook de destination (doit être un endpoint https:// sécurisé).
(Optionnel) Configurez des en-têtes HTTP personnalisés si votre serveur de réception nécessite des jetons d’en-tête spécifiques.
(Optionnel) Générez un Secret de signature HMAC pour vérifier l’authenticité des charges utiles.
Cliquez sur Enregistrer pour activer.

Structure de la charge utile

Chaque charge utile est envoyée sous forme d’objet JSON contenant des détails sur l’événement et le chat associé :

{
  "id": "5c6f8a0b-1234-4567-890a-bcdef1234567",
  "type": "contact",
  "event": "contact_created",
  "created_at": "2026-08-07T10:12:33.412Z",
  "chat_id": 42,
  "data": {
    "id": "b1e23456-7890-4abc-def0-1234567890ab",
    "firstname": "Ana",
    "email": "ana@example.com",
    "phone": "+33612345678",
    "source": "form",
    "kind": "lead_capture",
    "conversation_id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "history": [
      {
        "type": "user",
        "content": "Je souhaite réserver une démo pour demain",
        "manual": true,
        "timestampz": "2026-08-07T10:11:54.000Z"
      },
      {
        "type": "assistant",
        "content": "Bien sûr ! Quel créneau vous convient le mieux ?",
        "manual": false,
        "timestampz": "2026-08-07T10:12:01.000Z"
      }
    ]
  }
}

L’objet data inclut uniquement les champs non vides. Les champs optionnels qui n’ont pas été fournis par le visiteur sont omis pour garder les charges utiles propres.

Intention du prospect et canaux (`kind`, `channel`, `whatsapp`)

Pour les événements de type contact, Attlas enrichit la charge utile avec l’intention et le canal d’origine :

kind : Identifie l’intention brute de création du contact :
- lead_capture : Soumission d’un formulaire classique de capture de prospect.
- human_request : Demande d’échange avec un humain.
- booking : Réservation de rendez-vous via Google Agenda.
- whatsapp : Engagement via un déclencheur WhatsApp.
channel : Nomme le canal de sortie lorsqu’il existe (par exemple "whatsapp" si le visiteur redirige vers WhatsApp ; omis si vide).
whatsapp : Le numéro WhatsApp du visiteur lorsqu’il est renseigné ou capturé.

Historique de conversation et objets messages

Lorsque conversation_id est présent dans data (pour contact_created, contact_updated et event_created), Attlas intègre l’historique complet des messages de la conversation dans data.history, du plus ancien au plus récent. Chaque message dans history contient :

type : "user" pour les messages du visiteur, ou "assistant" pour les réponses de l’IA.
content : Le contenu textuel du message.
manual : true lorsque le visiteur a saisi le message à la main, ou false s’il a été généré en cliquant sur une pilule de réponse rapide ou envoyé par l’assistant.
timestampz : Horodatage ISO 8601 de création du message.

Sécurité et vérification

Pour garantir que les requêtes proviennent d’Attlas, vous pouvez générer un Secret de signature dans les paramètres du webhook. Une fois activé, chaque requête inclut un en-tête X-Attlas-Signature contenant un horodatage et une signature HMAC-SHA256 (t=timestamp,v1=signature).

Livraison, nouvelles tentatives et surveillance

Contrôles de sécurité : les URL de destination doivent utiliser https:// public. Les adresses localhost et IP privées sont bloquées.
Délais d’attente et nouvelles tentatives : les requêtes ont un délai de 10 secondes. Si votre serveur renvoie une erreur 5xx ou expire, Attlas retente automatiquement la livraison jusqu’à 3 fois avec un backoff exponentiel.
Journaux de livraison : vous pouvez consulter les tentatives de livraison récentes, les codes de statut et les messages d’erreur directement dans la boîte de dialogue des paramètres d’Attlas.

Home

Apprendre

Événements clés

Comment configurer les Webhooks

Structure de la charge utile

Intention du prospect et canaux (`kind`, `channel`, `whatsapp`)

Historique de conversation et objets messages

Sécurité et vérification

Livraison, nouvelles tentatives et surveillance

​Événements clés

​Comment configurer les Webhooks

​Structure de la charge utile

​Intention du prospect et canaux (kind, channel, whatsapp)

​Historique de conversation et objets messages

​Sécurité et vérification

​Livraison, nouvelles tentatives et surveillance

Événements clés

Comment configurer les Webhooks

Structure de la charge utile

Intention du prospect et canaux (`kind`, `channel`, `whatsapp`)

Historique de conversation et objets messages

Sécurité et vérification

Livraison, nouvelles tentatives et surveillance