Créer et gérer un webhook

Un webhook prévient l’un de vos systèmes dès qu’un fait survient dans Illizeo : une embauche, une absence validée, un document signé, un shift publié. Illizeo envoie alors un message signé à l’adresse que vous avez choisie. Là où un jeton API laisse un système venir lire, le webhook le prévient. Cet article explique comment créer un webhook, lui transmettre son secret, le modifier, le tester, le suspendre et le supprimer. Il s’adresse aux administrateurs.

Avant de commencer #

• L’écran se trouve dans Paramètres › Gérer Illizeo › Webhooks. L’entrée n’apparaît que si votre abonnement comprend les webhooks (ils sont ouverts pendant la période d’essai) et si l’un de vos rôles porte le droit « Voir les webhooks et leurs livraisons ».
• Créer, modifier, tester, désactiver ou supprimer un webhook, et renouveler son secret, demandent le droit « Créer / modifier / supprimer un webhook » au palier Exécuter. Par défaut, seul le rôle Administrateur porte ces droits, qui se règlent dans Paramètres › Gérer les employés › Rôles des employés (voir Permissions & rôles).
• Ces droits sont distincts de ceux des jetons API : on peut confier les webhooks sans confier les jetons.
• Le système récepteur doit exposer une adresse publique en https://. Sa mise en place est décrite dans Recevoir et vérifier un webhook.

La liste des webhooks #

Chaque ligne montre :

• Webhook : le nom et l’adresse de réception ;
• Événements : les trois premiers abonnements, puis « +n » ;
• Dernière livraison : son statut et sa date, ou Jamais (les tests ne comptent pas) ;
• Statut : l’interrupteur d’activation, avec la mention En échec depuis quand les livraisons échouent, ou Désactivé après échecs ;
• Actions : Voir, Modifier, Supprimer.

Le bouton Documentation, présent si vous avez aussi accès aux jetons API, ouvre la documentation de l’API, qui liste les événements.

Créer un webhook #

1. Cliquez sur Nouveau webhook (ou Créer le premier webhook si la liste est vide).
2. Nom (obligatoire, 100 caractères au plus) : le système prévenu, par exemple « Logiciel de paie ».
3. Adresse de réception : l’adresse qui recevra les messages. Elle doit commencer par https:// ; une adresse de réseau interne est refusée.
4. Événements (au moins un) : cochez les événements un à un, ou une famille entière.
5. Cliquez sur Créer le webhook. Il est actif aussitôt.

Cocher une famille (par exemple Absences, code absence.*) abonne le webhook à tous ses événements, y compris ceux que la famille gagnera plus tard. Les familles des modules non activés dans votre espace n’apparaissent pas. Le détail de chaque événement est dans le Catalogue des événements webhook.

Transmettre le secret de signature #

À la création, la fenêtre Secret de signature affiche le secret du webhook (il commence par whsec_) et un exemple de code sous Vérifier une livraison. Le système récepteur s’en sert pour vérifier que chaque message vient bien d’Illizeo. Copiez-le, transmettez-le par un canal sûr à la personne qui configure le récepteur, puis cliquez sur Je l’ai enregistré.

Le secret n’est plus jamais affiché ensuite : la page du webhook n’en montre que le début. S’il est perdu, renouvelez-le.

Modifier, tester, renouveler le secret #

• Modifier (icône de la liste ou bouton de la page du webhook) : la fenêtre Modifier le webhook permet de changer le nom, l’adresse et les événements, puis d’Enregistrer. Le secret ne change pas.
• Envoyer un test (page du webhook) : envoie tout de suite un événement ping à l’adresse, en une seule tentative, sans relance. Un message indique « Test livré » avec le code de réponse, ou « Test échoué » avec la raison. Le test apparaît dans les livraisons et ne compte pas dans la consommation.
• Renouveler le secret (page du webhook) : le nouveau secret est créé dès le clic, sans demande de confirmation, et s’affiche une seule fois. L’ancien ne signe plus rien : les messages suivants seront refusés par le récepteur tant qu’il n’a pas reçu le nouveau. Prévenez la personne qui le gère avant de cliquer.

Désactiver ou supprimer #

• Désactiver : basculez l’interrupteur de la colonne Statut. Plus rien n’est envoyé, et les événements survenus pendant la désactivation ne sont pas mis de côté : réactivé, le webhook ne reçoit que les nouveaux. Réactiver efface aussi la série d’échecs en cours.
• Supprimer : l’icône Supprimer ouvre la confirmation Supprimer le webhook. Le système récepteur n’est plus prévenu, et le journal des livraisons de ce webhook est supprimé avec lui.

À savoir #

• Un webhook qui échoue sans interruption pendant trois jours est désactivé automatiquement, et son créateur prévenu (voir Suivre les livraisons et les relances).
• Les créations, modifications, suppressions, activations et désactivations à la main, et les renouvellements de secret sont tracés dans Paramètres › Gérer Illizeo › Logs utilisateurs. La valeur du secret n’y figure jamais.
• Les messages portent surtout des identifiants et des états, jamais le nom d’une personne ni un montant de salaire : pour le détail, le système récepteur relit la ressource par l’API avec un jeton (voir Créer et gérer les jetons API).
• Plusieurs webhooks peuvent écouter le même événement : chacun reçoit son message.

Questions fréquentes #

Je ne vois pas le bouton « Nouveau webhook ». #

Il demande le droit « Créer / modifier / supprimer un webhook » au palier Exécuter.

L’enregistrement refuse mon adresse. #

Elle doit commencer par https:// et désigner un serveur joignable depuis Internet. Une adresse qui mène à un réseau interne est refusée.

Une famille que j’attends n’apparaît pas. #

Son module n’est pas activé dans votre espace : Planification, Annualisation, Budget, BDESE, Paie suisse et Flex Office n’ont d’événements que si le module l’est.