Comment recevoir mes leads par webhook ?

Ce que votre serveur reçoit

Un webhook sortant est un appel HTTPS que nous émettons vers votre serveur, un appel par lead livré. Vous n'interrogez rien : c'est nous qui poussons, au moment où le lead vous est livré.

Par défaut, l'appel est un POST en application/json, signé, et son corps est un objet plat. Les valeurs vides ne sont pas envoyées : une clé absente signifie que ce lead ne porte pas ce champ.

• leadReference : notre référence du lead. Stable, unique, à utiliser comme clé d'idempotence.
• deliveredAt : date de livraison, au format ISO 8601 en UTC.
• campaignName : nom de la campagne qui a produit le lead.
• leadStatus, statut du lead, en valeur brute : unknown, unreachable, unvalid, unqualified, valid, appointed, converted, cancelled.
• firstName et lastName : identité du prospect.
• emailAddress et phoneNumber : coordonnées, en clair.
• streetAddress, zipCode, cityName : adresse postale.
• userSentiment et provenanceName : ressenti déclaré et provenance de la collecte.
• callAttempts : le nombre d'appels que vous avez enregistrés chez nous.
• labels : vos étiquettes, réunies en une seule chaîne séparée par des virgules.
• qualification : objet portant les réponses de qualification du prospect.

Ces champs sont stables : vous pouvez écrire votre code en vous appuyant dessus. Les réponses de qualification varient selon la verticale : elles sont donc regroupées sous qualification.

Un lead qui vient d'être livré porte leadStatus à unknown. La signification des huit valeurs est détaillée dans Que signifient les huit statuts d'un lead ?.

Le chemin, depuis le tableau de bord

1. Ouvrez l'écran Intégration

Dans le menu de gauche, cliquez sur Intégration. L'écran Applications & notifications s'ouvre sur l'onglet Mes intégrations, qui liste vos flux existants.

2. Cliquez sur la carte « Webhook sortant »

Ouvrez l'onglet Catalogue, repérez la carte Webhook sortant et cliquez sur Configurer. Le constructeur s'ouvre avec l'étape webhook déjà en place. Vous pouvez donner un nom au flux dans le champ du haut : sans nom, il prendra celui de sa destination.

3. Vérifiez le déclencheur

Cliquez sur la première étape de la toile, Déclencheur. Le flux part en Temps réel : c'est le mode qui envoie à chaque lead livré.

Choisissez ensuite ce que le flux couvre : Toutes les campagnes, Certaines verticales ou Certaines campagnes. Tant que rien n'est coché, l'écran prévient : « Aucune sélection : rien ne passerait dans ce flux ».

4. Saisissez la méthode et l'URL

Cliquez sur l'étape Webhook sortant. La première rangée porte la méthode (POST par défaut, mais PUT, PATCH, GET et DELETE sont disponibles) et l'URL de votre point d'entrée. L'URL doit être en HTTPS et publique.

5. Réglez l'authentification attendue par votre outil

Sous Authentification, choisissez ce que votre serveur exige : Aucune, Jeton (un Authorization: Bearer), Basic, En-tête (vous nommez l'en-tête, par exemple X-Api-Key) ou Paramètre (une valeur ajoutée à l'URL). Votre secret est conservé chiffré et n'est plus réaffiché ensuite : laissez le champ vide pour le garder.

6. Choisissez la forme du corps

Sous Corps, trois choix. Automatique envoie nos champs sous nos noms, sans rien régler. Champs choisis vous laisse nommer chaque champ tel que votre CRM l'attend, en JSON ou en encodage de formulaire. JSON sur mesure vous laisse écrire le document exact avec des marqueurs.

Sous le corps, la case Omettre les paramètres dont le marqueur est absent retire du corps et de l'URL les valeurs qui manquent, au lieu de les envoyer vides.

7. Ouvrez les réglages avancés

Dépliez Réglages avancés. Ils regroupent quatre sections :

• En-tête : vos en-têtes personnalisés.
• Paramètres d'URL : des valeurs ajoutées à l'adresse appelée.
• Réponse : Identifiant créé, Message d'erreur et Mots d'erreur dans la réponse, pour lire ce que votre outil répond.
• Signature : la case Signer chaque envoi, cochée par défaut.

8. Enregistrez le flux, puis copiez le secret

Cliquez sur Enregistrer, en haut à droite. Le premier enregistrement crée votre secret de signature : il apparaît alors dans Réglages avancés, section Signature, sous la case Signer chaque envoi. Il est masqué, avec un bouton Afficher et un bouton Copier, et les noms des deux en-têtes à contrôler. Copiez-le et installez-le chez vous comme une variable d'environnement.

9. Envoyez un test réel

Ouvrez l'onglet Test du panneau, puis cliquez sur Envoyer un test. L'appel part vraiment, avec votre dernier lead livré, et la réponse de votre outil s'affiche telle quelle : code HTTP, durée, corps de la réponse. L'essai nécessite au moins un lead livré sur le compte.

10. Activez le flux

Cliquez sur Activer. Le flux passe d'un brouillon à un flux actif, et le prochain lead livré part chez vous. L'activation est refusée si l'URL manque, si elle n'est pas en HTTPS, si le gabarit cite un champ inexistant ou n'est pas du JSON valide, ou si un mode d'authentification est choisi sans secret.

Les en-têtes de chaque appel

Chaque appel porte les en-têtes suivants, en minuscules.

• x-yacla-signature : la signature, en hexadécimal minuscule.
• x-yacla-timestamp : l'horodatage de l'envoi, en secondes depuis l'époque Unix.
• content-type : application/json, ou application/x-www-form-urlencoded si vous avez choisi le format formulaire.
• authorization : présent seulement si vous avez choisi Jeton ou Basic.
• Vos propres en-têtes, ajoutés dans les réglages avancés.

Six noms d'en-tête sont réservés et ne peuvent pas être utilisés : host, content-length, connection, transfer-encoding, x-yacla-signature et x-yacla-timestamp.

Vérifier la signature chez vous

La signature est un HMAC-SHA256. Le message signé est l'horodatage, un point, puis le corps de la requête. Le secret est celui que vous avez copié à l'étape 8, après l'enregistrement.

1. 1.Lisez le corps de la requête brut, avant toute désérialisation JSON.
2. 2.Lisez l'en-tête x-yacla-timestamp.
3. 3.Concaténez l'horodatage, le caractère ., puis le corps brut.
4. 4.Calculez le HMAC-SHA256 de cette chaîne avec votre secret de signature, en sortie hexadécimale.
5. 5.Comparez le résultat à l'en-tête x-yacla-signature, en temps constant.
6. 6.Rejetez l'appel si les deux diffèrent, ou si l'horodatage est trop ancien.

Attention à deux points. Si vous re-sérialisez le JSON avant de calculer le HMAC, les espaces et l'ordre des clés changent, et la comparaison échoue. Et sur une méthode sans corps, GET ou DELETE, le message signé est l'horodatage suivi du point, rien de plus.

Les précautions de comparaison et de fraîcheur de l'horodatage sont détaillées dans Comment vérifier la signature de vos webhooks ?.

Ce que votre serveur doit répondre

Répondez tout de suite, puis traitez le lead en arrière-plan : un traitement trop long dépasse le délai d'attente, même si votre serveur a bien reçu les données.

• Un code de 200 à 299 vaut acceptation. Rien d'autre n'est traité comme un succès.
• 408, 429, 500, 502, 503 et 504 sont lus comme une panne passagère. La livraison reste En attente au journal.
• Tout autre code, 400 et 422 compris, est un échec définitif. La livraison passe en Échec, avec le motif que votre serveur a renvoyé.
• Aucune redirection n'est suivie : un 301 ou un 302 compte comme un échec.
• Au-delà de dix secondes sans réponse, nous abandonnons l'appel.

Nous lisons le corps de votre réponse et nous en gardons les 300 premiers caractères au journal. Renvoyez donc un message d'erreur lisible, par exemple « le champ owner_id est obligatoire » : il apparaîtra au journal et vous fera gagner du temps au diagnostic.

Le comportement en cas d'indisponibilité prolongée est décrit dans Que se passe-t-il si mon endpoint est indisponible ?. Après une panne de votre côté, contrôlez le journal, puis récupérez les leads manquants avec un export.

Adapter la requête à votre CRM

Si votre CRM impose sa propre forme de document, le mode JSON sur mesure vous laisse l'écrire, avec des marqueurs {{champ}} pour nos valeurs. La palette sous la zone de saisie liste les noms exacts disponibles sur votre compte. Vérifiez l'orthographe : un marqueur mal écrit donne un champ vide, sans message d'erreur.

Si un nœud Transformer les données est posé au-dessus de cette étape, les champs qu'il produit deviennent eux aussi des marqueurs disponibles : un nœud qui produit sexe depuis votre réponse d'origine rend {{sexe}} utilisable ici, avec la valeur déjà convertie.

• Un marqueur accepte un chemin pointé : {{qualification.budget}}.
• {{phoneNumber|digits}} retire espaces et signes, pour les champs téléphone qui les refusent.
• {{deliveredAt|date}} rend AAAA-MM-JJ, et |datetime rend l'horodatage complet.
• {{cityName|upper}}, |lower et |trim normalisent une chaîne.
• {{leadStatus|default:nouveau}} comble un champ obligatoire chez vous quand le nôtre est vide.
• Les caractères spéciaux sont échappés automatiquement : un prospect nommé O'Brien ne casse pas votre document.

Les marqueurs fonctionnent aussi dans l'URL et dans les paramètres d'URL : https://crm.exemple.fr/contacts/{{leadReference}} est une adresse valide, et l'encodage est appliqué automatiquement. L'adresse obtenue est revérifiée après substitution.

Dans la section Réponse des réglages avancés, deux champs vous font gagner du temps au diagnostic. Identifiant créé indique où lire, dans la réponse de votre CRM, l'identifiant de la fiche créée, par exemple data.id. Message d'erreur indique où lire son message, par exemple errors.0.message. Les deux apparaissent ensuite au journal.

Suivre les envois au journal

Le flux porte deux vues, Flux et Historique. L'historique montre les soixante dernières exécutions.

Une exécution correspond au passage d'un lead dans le flux : s'il traverse deux étapes, il tient sur une seule ligne, avec ses deux étapes détaillées dessous. Pour chacune, vous voyez la date, le lead, la destination, le statut et le détail. Quatre statuts existent : Envoyé, Échec, En attente et Ignoré, et le nombre de tentatives est affiché à côté du statut.

Vous pouvez n'afficher que les exécutions en erreur : chaque passage reste affiché en entier, étapes réussies comprises.

Une livraison est unique par lead et par étape de flux. En cas de reprise, vous pouvez recevoir deux fois la même leadReference : ignorez simplement le doublon.

Un lead absent du journal n'est pas passé par le flux. Vérifiez le périmètre du déclencheur, les filtres du flux, et pourquoi une campagne ne reçoit rien.

Limites à connaître

• L'URL doit être en HTTPS. Les adresses internes et privées sont refusées, à l'enregistrement comme à l'envoi.
• Le délai d'attente est de dix secondes, sans exception.
• Le secret de signature est créé au premier enregistrement, puis reconduit. Il n'y a pas de rotation en libre-service : pour en obtenir un nouveau, retirez l'étape et recréez-la, puis mettez à jour votre vérification.
• Le secret d'authentification de votre outil, lui, n'est jamais réaffiché. Vous pouvez le remplacer, pas le relire.
• Un essai lancé avant le premier enregistrement part sans secret de signature : enregistrez d'abord.
• Un champ absent du lead n'interrompt rien. La clé est omise, et signalée dans l'essai.
• Un gabarit invalide ou un champ inconnu empêche d'activer le flux, mais pas de l'enregistrer comme brouillon.
• Nous recommandons de garder la signature active : c'est elle qui vous garantit que l'appel vient bien de nous.
• Ouvrir cet écran demande le droit de voir les intégrations, et créer ou modifier un flux demande celui de les gérer. Voir Rôles et droits.