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.
• internalNote et callAttempts : votre note interne et le nombre d'appels 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 seize champs ne bougent pas : vous pouvez écrire du code contre eux. Les réponses de qualification, elles, changent d'une verticale à l'autre, c'est pourquoi elles sont regroupées sous qualification au lieu d'être mises à plat.

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 liste vos intégrations actives, les automatisations proposées, puis le catalogue des destinations.

2. Cliquez sur la carte « Webhook sortant »

La carte se trouve sous le titre Ajouter une intégration. Le constructeur s'ouvre avec l'étape webhook déjà posée. 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, et laissez-la sur Temps réel. C'est le mode qui envoie à chaque lead livré. Le panneau de droite permet aussi de restreindre le périmètre à certaines verticales ou à certaines campagnes.

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 chiffré chez nous et ne vous est jamais réaffiché : laisser le champ vide le conserve.

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.

7. Enregistrez le flux

Cliquez sur Enregistrer, en haut à droite. Cet enregistrement crée votre secret de signature : il n'existe pas avant.

8. Ouvrez les réglages avancés

Dépliez Réglages avancés, puis la section Signature. Vous y trouvez le Secret de signature, masqué, avec un bouton pour l'afficher et un pour le copier. Copiez-le et installez-le chez vous comme une variable d'environnement. Cette section porte aussi vos en-têtes personnalisés, vos paramètres d'URL, et les deux chemins de lecture de la réponse.

9. Envoyez un test réel

Ouvrez l'onglet Test du panneau, puis cliquez sur Envoyer un test. L'appel part vraiment, sur votre dernier lead livré, et la réponse de votre outil s'affiche telle quelle : code HTTP, durée, corps de la réponse. S'il n'existe aucun lead livré sur le compte, l'essai vous le dit au lieu de fabriquer un faux lead.

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 vous sont refusés, parce qu'ils appartiennent au transport ou à nous : 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.

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.

Deux pièges valent d'être nommés. Re-sérialiser le JSON avant de calculer le HMAC change les espaces et l'ordre des clés : la comparaison échouera pour de bonnes valeurs. 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 le plus tôt possible, puis traitez en asynchrone. Un traitement synchrone lent finit par dépasser notre délai d'attente, alors que votre serveur a bien reçu le lead.

• 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. C'est le meilleur outil de diagnostic dont vous disposez : une phrase comme « le champ owner_id est obligatoire » se corrige seule, là où un 422 nu envoie tout le monde au support.

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 : une faute de frappe dans un marqueur ne provoque aucune erreur à l'envoi, seulement un champ vide à chaque lead.

• 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.
• L'échappement est fait par nous : 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 les 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 Journal. Le journal montre les trente derniers envois : quand, quel lead, quelle destination, quel statut, et le détail. Quatre statuts existent : Envoyé, Échec, En attente et Ignoré. Le nombre de tentatives est affiché à côté du statut.

Une livraison est unique par lead et par étape de flux. Recevoir deux fois la même leadReference reste possible en cas de reprise : traitez-la comme une clé d'idempotence et ignorez le doublon.

Un lead qui n'apparaît nulle part au journal n'est pas un problème d'envoi : c'est que le flux ne l'a pas vu passer. 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.
• Désactiver la signature est possible, et déconseillé. Sans elle, quiconque connaît votre URL peut injecter de faux leads chez vous.
• 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.