Connexion Essayez gratuitement →
Voir les catégories

Recevoir et vérifier un webhook

Wilfrid Paul Robert Dusseaux
Mis à jour le 05.11.2026

3 mins de lecture

0:00 4:33

Cet article s’adresse aux développeurs qui reçoivent les webhooks d’Illizeo : la forme de la requête, ses en-têtes, le contenu du message, la vérification de la signature, la réponse attendue et la gestion des doublons. L’abonnement lui-même se crée dans l’application (voir Créer et gérer un webhook).

Avant de commencer #

  • Exposez une adresse publique en https://. Les adresses http, et celles qui mènent à un réseau interne, sont refusées à l’enregistrement et à chaque envoi.
  • Obtenez de l’administrateur le secret de signature du webhook. Il commence par whsec_ et n’est affiché qu’une fois, à la création ou au renouvellement : conservez-le comme un mot de passe.

La requête #

Chaque livraison est une requête POST dont le corps est un objet JSON (Content-Type: application/json). Elle porte ces en-têtes :

En-tête Contenu
Illizeo-Event Le code de l’événement, par exemple absence.approved.
Illizeo-Event-Id L’identifiant de l’événement, le même pour toutes les tentatives et pour tous les webhooks qui l’écoutent.
Illizeo-Delivery L’identifiant de la livraison à ce webhook, le même d’une tentative à l’autre.
Illizeo-Signature La signature, sous la forme t=<horodatage unix>,v1=<signature hexadécimale>.
User-Agent Illizeo-Webhooks/1.0

Le message #

Le corps contient toujours cinq champs :

  • id : l’identifiant de l’événement (repris dans Illizeo-Event-Id) ;
  • event : le code de l’événement ;
  • occurred_at : la date et l’heure du fait, au format ISO 8601 ;
  • tenant : le compte de l’entreprise (son sous-domaine) ;
  • data : les identifiants et les états propres à l’événement.

Exemple : {"id":"…","event":"absence.approved","occurred_at":"…","tenant":"…","data":{"absence_id":…,"employee_id":…,"absence_type_id":…,"from":"…","to":"…","status":"…"}}

Le message porte des identifiants, des dates, des états et, pour certains événements, des quantités (des heures, par exemple). Il ne contient jamais le nom d’une personne, un numéro d’assuré social, un montant de salaire ni une pièce jointe. Pour le détail, relisez la ressource par l’API avec un jeton (voir API publique : le guide du développeur). Les champs de data de chaque événement sont listés dans le Catalogue des événements webhook.

Le message JSON d'une livraison de test déplié dans le tableau des livraisons : champs id, data (ici le message de test et endpoint_id), event (ping), tenant et occurred_at
Le message envoyé, tel que le reçoit votre système.

Vérifier la signature #

  1. Lisez le corps brut de la requête, avant tout décodage JSON : la signature porte sur les octets reçus.
  2. Découpez l’en-tête Illizeo-Signature : la valeur après t= est l’horodatage, celle après v1= la signature.
  3. Calculez un HMAC-SHA256 avec le secret du webhook comme clé, sur la chaîne formée de l’horodatage, d’un point et du corps brut : <t>.<corps brut>. Exprimez le résultat en hexadécimal.
  4. Comparez-le à v1 avec une comparaison en temps constant (par exemple crypto.timingSafeEqual en Node.js, hash_equals en PHP, hmac.compare_digest en Python).
  5. Refusez le message si l’horodatage s’écarte de plus de 5 minutes de votre heure : cela bloque le rejeu d’un message intercepté.

La fenêtre qui affiche le secret donne un exemple en Node.js, sous Vérifier une livraison. Chaque tentative est signée au moment de son envoi, avec le secret en vigueur : après un renouvellement du secret, toutes les livraisons, relances comprises, sont signées avec le nouveau. Il n’y a pas de période pendant laquelle les deux secrets sont valides : coordonnez le renouvellement avec l’administrateur.

L'en-tête de la documentation de l'API : présentation, dont le paragraphe Webhooks qui décrit l'en-tête Illizeo-Signature, le calcul HMAC-SHA256, la tolérance de 5 minutes, le délai de réponse de 10 secondes et les relances, puis l'URL de base
La documentation de l’API rappelle le format de la signature et les relances.

Répondre #

  • Répondez par un code 2xx en moins de 10 secondes. Tout autre code, une absence de réponse ou une redirection (qui n’est pas suivie) compte comme un échec.
  • Répondez d’abord, traitez ensuite : mettez le message en file de votre côté, puis relisez la ressource par l’API si besoin.
  • Après un échec, Illizeo relance la livraison 1 minute, 5 minutes, 30 minutes, 2 heures puis 12 heures plus tard, soit six tentatives en tout. Un webhook qui échoue sans interruption pendant trois jours est désactivé.

Doublons et ordre d’arrivée #

  • Un même événement peut arriver plus d’une fois, par exemple si votre réponse a dépassé les 10 secondes alors que le message était traité. Gardez les Illizeo-Event-Id déjà traités et ignorez un doublon.
  • Les relances peuvent faire arriver un événement après un plus récent. Fiez-vous à occurred_at, ou relisez l’état courant de la ressource par l’API.

Le message de test #

Le bouton Envoyer un test de la page du webhook envoie un événement ping, signé comme les autres, dont data contient endpoint_id et un court message. Répondez-y par un code 2xx comme à tout autre message. Un test n’est jamais relancé.

À savoir #

  • La documentation de l’API, dans l’application, liste tous les événements et les champs de leur data, dans sa carte Événements webhook.
  • Les familles d’événements d’un module (Planification, Annualisation, Budget, BDESE, Paie suisse, Flex Office) ne sont émises que si le module est activé dans l’espace.
Mis à jour le 05.11.2026