Help desk webhooks tell your tools as soon as a ticket moves: a ticket filed, a status that changes, a public reply, a service commitment missed, a satisfaction rating. Your tool no longer has to poll the API: Illizeo sends it the event, signed, with the ticket, and sends it again if it does not answer. This article is for the developers who build the receiver and for the help desk administrator.
Before you start #
- The help desk module must be installed, and your subscription must include API access and webhooks.
- Only the tickets of services open to the API send events (see The help desk API).
- You need a token that carries
helpdesk_tickets:read(it bounds what the subscription receives) andhelpdesk_webhooks:write(to subscribe), created by a person who holds Administer the help center at the Execute level. - The receiver exposes a public
https://address and checks the signature: see Receiving and verifying a webhook.
The five events #
| Code | On screen | Sent when | On top of the ticket |
|---|---|---|---|
helpdesk.ticket.created |
Ticket created | A ticket is filed, whatever the channel (employee space, portal, e-mail, agent, website widget, Microsoft Teams, API), follow-ups included. | — |
helpdesk.ticket.status_changed |
Ticket status changed | The status changes, whoever makes the change: an agent, the requester, a rule, the API, a merge, automatic closure. A transfer to another service, which resets the ticket to New, does not send it. | de, vers |
helpdesk.ticket.public_reply |
Public reply on a ticket | A public reply is written in the thread, by the team or the requester, including a rule’s automatic reply and the common message of a major incident. | message |
helpdesk.ticket.sla_breached |
Service commitment breached | The escalation of a missed deadline goes out, once per commitment. | engagement (premiere_reponse or resolution), echeance |
helpdesk.ticket.satisfaction_received |
Satisfaction rating received | The requester answers the satisfaction survey. | note (1 to 5), commentaire |

Subscribing to helpdesk.* subscribes to the whole family, including events added to it later. One action can produce several events: a team reply that resolves the ticket sends the public reply, then the status change.
Subscribing #
The subscription is created through the API, with the token that will bound its content:
POST /v1/helpdesk/webhooks
Authorization: Bearer illz_…
Content-Type: application/json
{
"url": "https://n8n.your-company.co.uk/webhook/illizeo-helpdesk",
"events": ["helpdesk.ticket.created", "helpdesk.ticket.public_reply"],
"name": "n8n"
}
- The response, a 201, returns
id,eventsandsecret, the signing secret, which starts withwhsec_. It is only given once: store it in the receiver straight away. TheLocationheader gives the subscription’s address. - Only help desk events are accepted, one by one or as
helpdesk.*. The address must use https and be reachable from the internet; otherwise the response is 422. Without webhooks in your Illizeo subscription, it is 403FONCTIONNALITE_NON_INCLUSE. - To unsubscribe:
DELETE /v1/helpdesk/webhooks/{id}, with the same token. A subscription created by another token answers 404.
The subscription then appears under Settings › Manage Illizeo › Webhooks, with its API token. Its page lets you follow its deliveries, try it with Send a test, Rotate secret, deactivate it or delete it (see Creating and managing a webhook).

You can also create the subscription from the screen: in Settings › Manage Illizeo › Webhooks, the New webhook window asks for an API token as soon as a Help center event is ticked. Only your own active tokens are offered (you need to be able to read the API tokens): the subscription only receives what that token can read.
What your tool receives #
Each delivery is a JSON POST, with the envelope of all Illizeo webhooks: id (the event’s identifier), event, occurred_at, tenant and data. For the help desk, data carries:
object_type("ticket") andobject_id;object: the ticket in its API form — number, subject, description, status, priority, service, type, channel, requester (name and e-mail), agent, dates, deadlines, form answers, external reference; the fields and their codes are detailed in The help desk API;- the event’s own keys, given in the table above.
messagehas the form of an API message:cote(equipeordemandeur),auteur,via_api,le,corpsin HTML andpieces(name and size).
{
"id": "6f1c2b0e-…",
"event": "helpdesk.ticket.status_changed",
"occurred_at": "2026-11-20T09:05:00+00:00",
"tenant": "your-space",
"data": {
"object_type": "ticket",
"object_id": 812,
"object": { "numero": "AST-000812", "objet": "File server unreachable", "statut": "resolved", "priorite": "high", "…": "…" },
"de": "new",
"vers": "resolved"
}
}
The ticket is as it stood at the time of the action. Service and type names are in the language of the person who created the token. The subscription’s page shows each payload sent, with Show payload:

Who receives what #
A subscription only receives what its token reads. An event goes to it only if:
- the ticket belongs to a service open to the API;
- the subscription’s token is active (neither deactivated, revoked nor expired), carries
helpdesk_tickets:readand belongs to the person who created the subscription; - that person is active and reaches the ticket: an agent of its service, or the help desk administrator.
Otherwise nothing goes to that subscription, not even the ticket number. Nothing goes out either for demo data, when the module is switched off, or for an action that was rolled back. Regenerating the token changes nothing for the subscription; revoking it or letting it expire stops every delivery.
What it never contains #
- An internal note: none is sent, even if the token carries
helpdesk_notes:read, and writing a note sends no event. - The ticket’s thread: neither its messages nor its timeline. Only the message of a public reply goes out, with its event.
- The content of attachments: only their name and size.
- Who made the change: the payload does not say who changed a status. For a reply,
message.auteurgives the name shown in the thread.
The rest is what the requester sees: their name and address, the subject, the description and the text of public replies go out to your tool. Choose a receiver you control.
Signature, retries and replay #
- Each delivery is signed: the
Illizeo-Signatureheader readst=<timestamp>,v1=<signature>, a hexadecimal HMAC-SHA256 computed with the secret over<t>.<raw body>. Recompute it, compare in constant time, and refuse a timestamp more than 5 minutes old: an intercepted message cannot then be replayed. - Answer with a 2xx code within 10 seconds. Otherwise the delivery is retried 1 minute, 5 minutes, 30 minutes, 2 hours then 12 hours later: six attempts in all.
- All attempts carry the same
Illizeo-Event-Id: keep the ones already processed and ignore duplicates. A retry may arrive after a more recent event: rely onoccurred_at, or read the ticket again through the API. - A failed delivery can be sent again by hand with Retry now, on the subscription’s page. A subscription that fails without interruption for three days is deactivated, and its creator notified.
Details are in Receiving and verifying a webhook and Monitoring deliveries and retries.
Good to know #
- Each successful delivery counts as one unit in the API platform usage; if the usage cap is reached, deliveries stop until the next period.
- The delivery log, payloads included, is kept for 30 days. It can be read under Settings › Manage Illizeo › Webhooks with the “Webhooks — View” permission.
- Several subscriptions can listen to the same event: each receives its own delivery, read with its own token.
- For the rest of a ticket (its thread, and its notes with the dedicated scope), read it again through the API.
