Les webhooks préviennent vos outils (Power Automate, n8n, Zapier, Make, votre système d’information) dès qu’un fait se produit dans le CRM : un compte créé, une opportunité gagnée, une cotisation payée… Votre outil n’a plus à interroger l’API en boucle : Illizeo lui envoie le fait, signé, et le renvoie s’il ne répond pas. Cet article explique comment créer un abonnement, ce que reçoit votre outil, comment vérifier la signature et ce qui se passe en cas d’échec. Il s’adresse aux administrateurs du CRM et aux développeurs qui construisent le récepteur.
Avant de commencer #
- Le module CRM doit être activé, et votre abonnement Illizeo doit comprendre les webhooks : sans eux, la tuile Webhooks et intégrations n’apparaît pas.
- Droits de la matrice des rôles, menu CRM, palier Accès : « Réglages du CRM : consulter » pour voir les abonnements et leurs livraisons ; « Réglages du CRM : créer » pour en créer ; « Réglages du CRM : modifier » pour les modifier, les activer ou les désactiver, renouveler un secret, envoyer un test ou relancer une livraison ; « Réglages du CRM : supprimer » pour en supprimer.
- Il faut un jeton d’API actif, créé dans Paramètres › Gérer Illizeo › Jetons API (voir Créer et gérer les jetons API), avec la lecture des objets à recevoir (« CRM — comptes », « CRM — contacts », « CRM — opportunités », « CRM — activités »). Un abonnement ne reçoit que ce que ce jeton peut lire.
Ouvrir les webhooks du CRM #
Ouvrez Paramètres › CRM › Webhooks et intégrations. La page liste les abonnements du CRM, avec pour chacun :
- Webhook : son nom, son adresse de réception et son Jeton d’API ;
- Événements : ceux qu’il écoute ;
- Dernière livraison, ou « Jamais » ;
- Statut : Actif ou Inactif, un interrupteur pour passer de l’un à l’autre, et les signaux d’échec : « 2 relance(s) échouée(s) d’affilée », En échec depuis une date, ou Désactivé après échecs ;
- Actions : voir la fiche de l’abonnement, le modifier ou le supprimer.
Sous la liste, la carte Intégrations propose les fichiers pour Power Automate et n8n (voir Relier le CRM à Power Automate et Relier le CRM à n8n).
Créer un abonnement #
- Cliquez sur Nouveau webhook (ou, sur une liste vide, Créer le premier webhook).
- Donnez un Nom qui désigne le système récepteur.
- Saisissez l’Adresse de réception : une adresse en https sur l’internet public. Une adresse de réseau interne (127.0.0.1, 10.x.x.x, ou un nom qui se résout en adresse privée) est refusée, à l’enregistrement comme à chaque envoi.
- Sous Jeton d’API, choisissez l’un de vos jetons actifs : seuls les jetons que vous avez créés sont proposés. Le champ le rappelle : « Seuls vos propres jetons sont proposés : l’abonnement ne reçoit que ce que ce jeton peut lire. » Sans jeton actif, l’écran invite à en créer un.
- Sous Événements, cochez ceux à recevoir : la famille CRM est seule proposée.
- Cliquez sur Créer le webhook.
- La fenêtre Secret de signature affiche le secret : copiez-le et confiez-le au système récepteur. Il ne sera plus affiché ; en cas de perte, renouvelez-le. La rubrique Vérifier une livraison donne un exemple de code. Cliquez sur Je l’ai enregistré.
Un abonnement créé par Power Automate depuis son connecteur apparaît aussi dans cette liste, relié au jeton de la connexion.
Les événements #
Chaque événement porte un code, que votre outil reçoit dans le champ event. Pour qu’il parte vers un abonnement, le jeton doit porter la lecture indiquée, et la personne qui a créé le jeton doit pouvoir lire la fiche, avec ses droits et sa portée, comme à l’écran.
| Code | À l’écran | Données en plus de l’objet | Lecture du jeton |
|---|---|---|---|
crm.account.created, .updated, .archived |
Compte créé, Compte modifié, Compte archivé | la fiche du compte (object) |
CRM — comptes |
crm.account.merged |
Comptes fusionnés | la fiche gardée, merged_id (le compte absorbé) |
CRM — comptes |
crm.contact.created, .updated |
Contact créé, Contact modifié | la fiche du contact | CRM — contacts |
crm.contact.attached |
Contact rattaché à un compte | la fiche, account_id |
CRM — contacts |
crm.opportunity.created |
Opportunité ou dossier créé | la fiche, kind (sale ou follow_up) |
CRM — opportunités |
crm.opportunity.stage_changed |
Changement d’étape | la fiche, kind, stage_id |
CRM — opportunités |
crm.opportunity.won, .lost |
Opportunité gagnée ou dossier réussi, Opportunité perdue ou dossier abandonné | la fiche, kind, outcome (le libellé de l’issue du pipeline) |
CRM — opportunités |
crm.activity.created |
Activité créée | la fiche de l’activité | CRM — activités |
crm.quote.sent, .accepted |
Devis envoyé, Devis accepté | opportunity_id, number, status |
CRM — opportunités |
crm.membership.created |
Adhésion créée | club_id, account_id, contact_id, status |
CRM — comptes |
crm.dues.paid, .overdue |
Cotisation payée, Cotisation en retard | membership_id, event_id, number, status |
CRM — comptes |
crm.event_registration.created |
Inscription à un événement | crm_event_id, contact_id, status, matching |
CRM — contacts |
crm.import.completed |
Import terminé | target, created, updated, rejected |
CRM — comptes |
- Un événement part quel que soit le chemin du geste : l’écran, l’API, un import (un événement par fiche créée) ou une tâche de nuit (« Cotisation en retard », par exemple).
- « Cotisation payée » ne part qu’au paiement qui solde la cotisation. « Opportunité gagnée ou dossier réussi » vaut pour les pipelines de vente et de suivi :
kindles distingue (voir Les pipelines de suivi : dossiers d’accompagnement et d’implantation). - Une activité privée d’une autre personne que le créateur du jeton n’est jamais envoyée. Un contact du formulaire public n’est nommé dans une inscription que si le jeton peut le lire. Un import n’est envoyé qu’à un jeton dont le créateur porte « Import et export CRM : consulter ».
Ce que reçoit votre outil #
Un appel POST, en JSON, vers l’adresse de réception. Le corps porte :
| Champ | Contenu |
|---|---|
id |
L’identifiant de l’événement : le même pour toutes ses relances ; servez-vous-en pour ne traiter un fait qu’une fois. |
event |
Le code de l’événement. |
occurred_at |
La date et l’heure du fait (ISO 8601). |
tenant |
L’identifiant de votre espace. |
data |
object_type et object_id, puis, pour un compte, un contact, une opportunité ou une activité, object : la fiche sous la forme de l’API v1, lue avec les droits du jeton ; pour les autres, les identifiants et états du tableau ci-dessus. |
Les en-têtes portent Illizeo-Event (le code), Illizeo-Event-Id (l’identifiant de l’événement), Illizeo-Delivery (le numéro de la livraison) et Illizeo-Signature. Un objet que le jeton ne peut pas lire n’est jamais envoyé, ni même son identifiant.
Vérifier la signature #
L’en-tête Illizeo-Signature a la forme t=<horodatage>,v1=<signature>. La signature est un HMAC-SHA256, en hexadécimal, calculé avec votre secret sur <t>.<corps brut>.
- Lisez
tetv1dans l’en-tête. - Recalculez le HMAC-SHA256 de l’horodatage, d’un point et du corps tel que reçu, octet pour octet, avant toute lecture du JSON.
- Comparez votre résultat à
v1par une comparaison à temps constant. S’ils diffèrent, rejetez l’appel. - Refusez un horodatage trop ancien (cinq minutes conseillées), pour qu’un appel enregistré ne puisse pas être rejoué.
- Ignorez un
iddéjà traité, puis répondez vite par un code 2xx et traitez le fait ensuite.
La fiche d’un abonnement #
Cliquez sur un abonnement pour ouvrir sa fiche :
- Envoyer un test envoie tout de suite un événement
ping, signé, jamais relancé, qui ne compte pas dans votre consommation ; - Renouveler le secret en fabrique un nouveau, affiché une seule fois : l’ancien cesse de valoir ;
- Modifier change le nom, l’adresse ou les événements ; seule la personne qui a créé l’abonnement peut en changer le jeton, pour l’un des siens ;
- les compteurs Livrées (30 j), En relance, Échouées (30 j) et En attente, et les Relances échouées d’affilée ;
- les Livraisons, filtrables par statut (Livrée, En relance, Échouée, En attente) : Date, Événement, Statut, Tentatives, Réponse (code HTTP et durée) et Prochaine relance. Voir la charge montre ce qui a été envoyé ; Relancer maintenant renvoie la livraison une fois.
Échecs, relances et suspension #
- Une livraison réussit quand votre récepteur répond par un code 2xx en moins de dix secondes. Une autre réponse, une redirection (jamais suivie) ou l’absence de réponse est un échec.
- Un échec est relancé automatiquement après 1 min, 5 min, 30 min, 2 h, puis 12 h : six tentatives en tout. Au-delà, la livraison est Échouée et ne repart qu’à la main, par Relancer maintenant, pour une seule tentative.
- Après cinq relances échouées d’affilée, toutes livraisons confondues, ou trois jours d’échecs continus, l’abonnement est suspendu : il passe Inactif, ses relances en attente s’arrêtent, et son créateur est prévenu, dans la cloche et par e-mail, s’il peut encore modifier les réglages du CRM.
- Pour le reprendre : réparez le récepteur, cliquez sur Envoyer un test, puis réactivez-le depuis la liste. Le compte des échecs ne repart à zéro qu’à la première livraison réelle réussie : d’ici là, un nouvel échec suspend de nouveau l’abonnement.
- Le journal des livraisons est gardé 30 jours. Supprimer un abonnement supprime aussi son journal.
À savoir #
- Un geste annulé (une erreur qui défait l’enregistrement, une simulation d’import) n’envoie rien : la livraison ne part qu’une fois le geste écrit.
- Les données de démonstration ne déclenchent aucun envoi, et rien ne part quand le module CRM est coupé.
- Chaque livraison réussie compte dans la consommation de l’API de votre abonnement, relances comprises une seule fois. Si le plafond de consommation est atteint, les livraisons s’arrêtent, sans relance. Le test ne compte pas.
- La liste Jeton d’API ne propose que vos propres jetons actifs : un abonnement reçoit ce que lit la personne qui a créé son jeton. Un abonnement relié au jeton d’une autre personne ne reçoit rien.
- Révoquer ou laisser expirer le jeton d’un abonnement l’empêche de rien recevoir : choisissez-en un autre avec Modifier.
- La création, la modification et la suppression d’un abonnement sont tracées ; la valeur du secret, jamais.
Questions fréquentes #
L’abonnement est actif, mais rien n’arrive. #
Vérifiez que le jeton est actif, qu’il porte la lecture de l’objet (« CRM — opportunités » pour un devis, par exemple) et que son créateur peut lire la fiche : un commercial dont la portée est « Les miens » ne reçoit que ses propres fiches. Vérifiez aussi la fiche de l’abonnement : une livraison En relance ou Échouée dit la réponse de votre récepteur.
Mon outil reçoit deux fois le même fait. #
Une relance peut arriver si votre récepteur a répondu trop tard ou par une erreur alors qu’il avait traité l’appel. Gardez les id déjà traités et ignorez les doublons.
