Les webhooks du Centre d’assistance préviennent vos outils dès qu’un ticket bouge : un ticket déposé, un statut qui change, une réponse publique, un engagement de service dépassé, une note de satisfaction. Votre outil n’a plus à interroger l’API en boucle : Illizeo lui envoie le fait, signé, avec le ticket, et le renvoie s’il ne répond pas. Cet article s’adresse aux développeurs qui construisent le récepteur et à l’administrateur du Centre.
Avant de commencer #
- Le module Centre d’assistance doit être installé, et votre abonnement doit comprendre l’accès à l’API et les webhooks.
- Seuls les tickets des services ouverts à l’API émettent (voir L’API du Centre d’assistance).
- Il faut un jeton qui porte
helpdesk_tickets:read(il borne ce que l’abonnement reçoit) ethelpdesk_webhooks:write(pour s’abonner), créé par une personne qui détient Administrer le Centre d’assistance au palier Exécuter. - Le récepteur expose une adresse publique en
https://et vérifie la signature : voir Recevoir et vérifier un webhook.
Les cinq événements #
| Code | À l’écran | Envoyé quand | En plus du ticket |
|---|---|---|---|
helpdesk.ticket.created |
Ticket créé | Un ticket est déposé, quel que soit le canal (espace salarié, portail, e-mail, agent, widget du site, Microsoft Teams, API), suite comprise. | — |
helpdesk.ticket.status_changed |
Statut d’un ticket changé | Le statut change, d’où que vienne le geste : un agent, le demandeur, une règle, l’API, une fusion, la clôture automatique. Le transfert vers un autre service, qui remet le ticket à Nouveau, n’en envoie pas. | de, vers |
helpdesk.ticket.public_reply |
Réponse publique sur un ticket | Une réponse publique s’écrit dans le fil, de l’équipe ou du demandeur, réponse automatique d’une règle et message commun d’un incident majeur compris. | message |
helpdesk.ticket.sla_breached |
Engagement de service dépassé | L’escalade d’une échéance dépassée part, une fois par engagement. | engagement (premiere_reponse ou resolution), echeance |
helpdesk.ticket.satisfaction_received |
Satisfaction reçue | Le demandeur répond à l’enquête de satisfaction. | note (de 1 à 5), commentaire |

S’abonner à helpdesk.* abonne à toute la famille, y compris aux événements qui s’y ajouteront. Un geste peut en produire plusieurs : une réponse de l’équipe qui résout le ticket envoie la réponse publique, puis le statut changé.
S’abonner #
L’abonnement se crée par l’API, avec le jeton qui en bornera le contenu :
POST /v1/helpdesk/webhooks
Authorization: Bearer illz_…
Content-Type: application/json
{
"url": "https://n8n.votre-entreprise.ch/webhook/illizeo-helpdesk",
"events": ["helpdesk.ticket.created", "helpdesk.ticket.public_reply"],
"name": "n8n"
}
- La réponse, en 201, rend
id,eventsetsecret, le secret de signature, qui commence parwhsec_. Il n’est donné qu’une fois : rangez-le aussitôt dans le récepteur. L’en-têteLocationdonne l’adresse de l’abonnement. - Seuls les événements du Centre sont acceptés, un à un ou par
helpdesk.*. L’adresse doit être en https et joignable depuis Internet ; sinon, la réponse est 422. Sans webhooks dans votre abonnement Illizeo, elle est 403FONCTIONNALITE_NON_INCLUSE. - Pour se désabonner :
DELETE /v1/helpdesk/webhooks/{id}, avec le même jeton. L’abonnement créé par un autre jeton répond 404.
L’abonnement apparaît ensuite dans Paramètres › Gérer Illizeo › Webhooks, avec son Jeton d’API. Sa page permet de suivre ses livraisons, de l’essayer avec Envoyer un test, de Renouveler le secret, de le désactiver ou de le supprimer (voir Créer et gérer un webhook).

Vous pouvez aussi créer l’abonnement depuis l’écran : dans Paramètres › Gérer Illizeo › Webhooks, la fenêtre Nouveau webhook demande un Jeton d’API dès qu’un événement du Centre d’assistance est coché. Seuls vos propres jetons actifs sont proposés (il faut pouvoir lire les jetons d’API) : l’abonnement ne reçoit que ce que ce jeton peut lire.
Ce que reçoit votre outil #
Chaque livraison est un POST en JSON, avec l’enveloppe de tous les webhooks d’Illizeo : id (l’identifiant de l’événement), event, occurred_at, tenant et data. Pour le Centre, data porte :
object_type("ticket") etobject_id;object: le ticket sous sa forme de l’API — numéro, objet, description, statut, priorité, service, type, canal, demandeur (nom et e-mail), agent, dates, échéances, réponses au formulaire, référence externe ; le détail des champs et de leurs codes est dans L’API du Centre d’assistance ;- les clés propres à l’événement, données dans le tableau ci-dessus.
messagea la forme d’un message de l’API :cote(equipeoudemandeur),auteur,via_api,le,corpsen HTML etpieces(nom et taille).
{
"id": "6f1c2b0e-…",
"event": "helpdesk.ticket.status_changed",
"occurred_at": "2026-11-20T09:05:00+00:00",
"tenant": "votre-espace",
"data": {
"object_type": "ticket",
"object_id": 812,
"object": { "numero": "AST-000812", "objet": "Serveur de fichiers injoignable", "statut": "resolved", "priorite": "high", "…": "…" },
"de": "new",
"vers": "resolved"
}
}
Le ticket est celui du moment du geste. Les noms du service et du type sont dans la langue de la personne qui a créé le jeton. La page de l’abonnement montre chaque charge envoyée, avec Voir la charge :

Qui reçoit quoi #
Un abonnement ne reçoit que ce que lit son jeton. Un événement part vers lui seulement si :
- le ticket appartient à un service ouvert à l’API ;
- le jeton de l’abonnement est actif (ni désactivé, ni révoqué, ni expiré), porte
helpdesk_tickets:readet appartient à la personne qui a créé l’abonnement ; - cette personne est active et atteint le ticket : agent de son service, ou administrateur du Centre.
Sinon, rien ne part vers cet abonnement, pas même le numéro du ticket. Rien ne part non plus pour les données de démonstration, quand le module est coupé, ni pour un geste annulé. Régénérer le jeton ne change rien à l’abonnement ; le révoquer ou le laisser expirer le prive de tout envoi.
Ce qui n’y figure jamais #
- Une note interne : aucune n’est envoyée, même si le jeton porte
helpdesk_notes:read, et écrire une note n’émet aucun événement. - Le fil du ticket : ni ses messages, ni sa chronologie. Seul le message d’une réponse publique part, avec son événement.
- Le contenu des pièces jointes : seulement leur nom et leur taille.
- L’auteur du geste : la charge ne dit pas qui a changé un statut. Pour une réponse,
message.auteurdonne le nom affiché dans le fil.
Le reste est ce que voit le demandeur : son nom et son adresse, l’objet, la description et le texte des réponses publiques sortent vers votre outil. Choisissez un récepteur que vous maîtrisez.
Signature, relances et rejeu #
- Chaque livraison est signée : l’en-tête
Illizeo-Signaturevautt=<horodatage>,v1=<signature>, un HMAC-SHA256 en hexadécimal calculé avec le secret sur<t>.<corps brut>. Recalculez-le, comparez en temps constant, et refusez un horodatage de plus de 5 minutes : un message intercepté ne pourra pas être rejoué. - Répondez par un code 2xx en moins de 10 secondes. Sinon, la livraison est relancée 1 minute, 5 minutes, 30 minutes, 2 heures puis 12 heures plus tard : six tentatives en tout.
- Toutes les tentatives portent le même
Illizeo-Event-Id: gardez ceux déjà traités et ignorez les doublons. Une relance peut arriver après un événement plus récent : fiez-vous àoccurred_at, ou relisez le ticket par l’API. - Une livraison échouée se renvoie à la main avec Relancer maintenant, sur la page de l’abonnement. Un abonnement qui échoue sans interruption pendant trois jours est désactivé, et son créateur prévenu.
Le détail est dans Recevoir et vérifier un webhook et Suivre les livraisons et les relances.
À savoir #
- Chaque livraison réussie compte une unité dans la consommation de la plateforme API ; si le plafond de consommation est atteint, les livraisons s’arrêtent jusqu’à la période suivante.
- Le journal des livraisons, charges comprises, est gardé 30 jours. Il se lit dans Paramètres › Gérer Illizeo › Webhooks avec le droit « Voir les webhooks et leurs livraisons ».
- Plusieurs abonnements peuvent écouter le même événement : chacun reçoit sa livraison, lue avec son propre jeton.
- Pour le reste d’un ticket (son fil, et ses notes avec le droit dédié), relisez-le par l’API.
