--- title: Recevoir et vérifier un webhook description: "Pour les développeurs : la requête, ses en-têtes, le message JSON, la vérification de la signature HMAC-SHA256, la réponse attendue et les doublons." url: "https://illizeo.com/centre-aide/webhooks-recevoir-et-verifier/" updated: "2026-11-05" category: Plateforme / Webhooks --- # Recevoir et vérifier un webhook 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](https://illizeo.com/centre-aide/webhooks-creer-et-gerer/)). ## 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=,v1=`. | | `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](https://illizeo.com/centre-aide/api-guide-du-developpeur/)). Les champs de `data` de chaque événement sont listés dans le [Catalogue des événements webhook](https://illizeo.com/centre-aide/webhooks-catalogue-des-evenements/). ![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](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/webhooks-recevoir-et-verifier-01.fr_.png?resize=800%2C118&quality=80&ssl=1) 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 : `.`. 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](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/webhooks-recevoir-et-verifier-02.fr_.png?resize=800%2C524&quality=80&ssl=1) 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. ### *Similaire*