Configurer des webhooks

Un webhook fait appeler par Swimlane une URL à vous chaque fois qu'un contact est créé, modifié ou supprimé. C'est la façon d'alimenter un CRM, un tableur, n8n ou Make sans interroger l'API en boucle.

Avant de commencer

Il vous faut une URL qui accepte des requêtes POST avec un corps JSON : un webhook n8n ou Make, un « catch hook » Zapier, ou votre propre endpoint.
Les webhooks vous appartiennent, ils ne sont pas partagés avec l'équipe. Chaque membre qui veut recevoir des événements crée les siens.

Créer un webhook

Cliquez sur Paramètres en bas de la barre latérale gauche.
Dans le groupe Intégrations, ouvrez Webhooks.
Cliquez sur Ajouter un webhook.
Collez votre URL du webhook. Elle doit commencer par http:// ou https://.
Sous Événements, cochez au moins un événement : Contact Created, Contact Updated, Contact Deleted (libellés en anglais).
Réglez le Nombre maximum de tentatives entre 1 et 5 (voir Nouvelles tentatives plus bas).
Cochez Générer une clé secrète pour recevoir des requêtes signées. Nous le recommandons pour toute URL exposée sur Internet.
Cliquez sur Créer le webhook.
Si vous avez demandé une clé, la fenêtre Secret du webhook l'affiche. Copiez-la tout de suite : elle ne sera plus jamais affichée. Cliquez ensuite sur Continuer.

Swimlane envoie une requête de test à votre URL dès la création du webhook.

Les trois événements

contact.created : un nouveau contact entre dans votre organisation, que vous l'ajoutiez vous-même, qu'il vienne d'un import ou qu'il apparaisse lors de la synchronisation d'une nouvelle conversation LinkedIn.
contact.updated : les informations propres au contact changent. C'est le cas quand vous modifiez le contact, par exemple en écrivant une note ou en l'archivant. C'est aussi le cas quand un import ou la synchronisation de la boîte de réception retrouve un contact existant avec de nouvelles valeurs, comme un nouveau titre ou une nouvelle photo.
contact.deleted : un contact est supprimé.

Il n'existe que ces trois événements. Aucun événement pour une réponse, un message, un tag, une liste ou un changement d'étape de pipeline, et ajouter un tag ou déplacer un contact dans un pipeline n'envoie pas contact.updated. Les actions sur plusieurs contacts à la fois (modifications ou suppressions groupées) et les modifications faites via l'API publique n'envoient aucun événement.

Le corps de la requête et la signature sont décrits dans Contenu des webhooks et vérification de la signature.

Tester, mettre en pause, modifier ou supprimer

Sur chaque webhook de la liste :

Cliquez sur le menu ⋮, puis Tester le webhook. Swimlane envoie un événement de test et affiche « Webhook de test envoyé avec succès ! » ou « Échec du test : » suivi de l'erreur. Le test n'est disponible que si le webhook est actif.
Utilisez l'interrupteur pour le mettre en pause ou le réactiver. Un webhook en pause ne reçoit rien, et les envois en attente sont abandonnés.
⋮ → Modifier change l'URL, les événements ou les tentatives. Cochez Régénérer la clé secrète pour obtenir une nouvelle clé (l'ancienne cesse de fonctionner).
⋮ → Supprimer le retire après confirmation.

Les badges de chaque webhook indiquent s'il est Actif, Signé (il a une clé secrète) et son nombre de tentatives.

Nouvelles tentatives

Un envoi réussit quand votre URL répond avec un statut 2xx en moins de 30 secondes.
Le Nombre maximum de tentatives est le nombre total d'essais. Avec 1, un envoi raté n'est pas retenté.
Entre deux essais, Swimlane attend 15 secondes, puis 30, 60 et 120 secondes.
Après le dernier essai, l'envoi est abandonné. L'application ne propose pas de journal des envois : journalisez les requêtes reçues de votre côté.

Bon à savoir

Les événements arrivent en une minute environ. Les envois partent par lots, une fois par minute.
Les webhooks de chaque membre entendent toute l'organisation. Quand un contact change, chaque membre de l'organisation qui a un webhook actif sur cet événement reçoit un envoi, quelle que soit la personne à l'origine du changement. Si deux membres pointent vers la même URL, elle reçoit l'événement deux fois.
Plusieurs organisations : si vous appartenez à plusieurs organisations, vos webhooks reçoivent les événements de toutes.
Répondez vite avec un 2xx et faites le traitement lourd ensuite, pour qu'un traitement lent ne soit pas compté comme un échec.
Un même événement peut vous parvenir deux fois, par exemple si votre serveur l'a traité mais a répondu trop tard. Rendez votre traitement rejouable sans effet de bord, en vous basant sur l'uuid du contact.

Dépannage

Échec du test : HTTP 404 / 405 : l'URL est fausse ou n'accepte pas POST. Dans n8n, l'URL de test n'écoute que pendant l'attente d'un événement de test : utilisez l'URL de production pour un workflow actif.
Rien n'arrive après une modification : vérifiez que le webhook est actif et abonné à cet événement, et que la modification envoie bien un événement (pas un tag, une liste ou une étape, ni une action groupée).