---
title: Help desk webhooks
description: "Be told as soon as a help desk ticket is filed, changes status, receives a public reply, misses a commitment or gets a satisfaction rating: the five events, the payload, the signature and retries."
url: "https://illizeo.com/en/centre-aide/help-desk-webhooks/"
updated: "2026-11-20"
category: Help desk
---

# Help desk webhooks

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](https://illizeo.com/en/centre-aide/help-desk-api/)).
- You need a token that carries `helpdesk_tickets:read` (it bounds what the subscription receives) and `helpdesk_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](https://illizeo.com/en/centre-aide/webhooks-receiving-and-verifying/).

## 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](https://illizeo.com/en/centre-aide/help-desk-major-incidents-and-problems/). | `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` |

![Help center family in the New webhook window: helpdesk.* box then the five events Ticket created, Ticket status changed, Public reply on a ticket, Service commitment breached and Satisfaction rating received, with their codes](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-webhooks-01.en_.png?resize=622%2C228&quality=80&ssl=1)
The five help desk events

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`, `events` and `secret`, the signing secret, which starts with `whsec_`. It is only given once: store it in the receiver straight away. The `Location` header 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 403 `FONCTIONNALITE_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](https://illizeo.com/en/centre-aide/webhooks-creating-and-managing/)).

![Page of a subscription created through the API: name, Active state, Send a test, Rotate secret and Edit buttons, receiving address, start of the signing secret, the five helpdesk events, creation date and Supervision API token](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-webhooks-02.en_.png?resize=800%2C183&quality=80&ssl=1)
A help desk subscription, linked to its token

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"`) and `object_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](https://illizeo.com/en/centre-aide/help-desk-api/);
- the event’s own keys, given in the table above. `message` has the form of an API message: `cote` (`equipe` or `demandeur`), `auteur`, `via_api`, `le`, `corps` in HTML and `pieces` (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**:

![Delivery table of a subscription: helpdesk.ticket.status_changed and helpdesk.ticket.public_reply deliveries delivered, then the JSON payload of a public reply expanded: the ticket in object and the message written through the API in message](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-webhooks-03.en_.png?resize=800%2C748&quality=80&ssl=1)
The payload of a public reply

## 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:read` and 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.auteur` gives 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-Signature` header reads `t=<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 on `occurred_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](https://illizeo.com/en/centre-aide/webhooks-receiving-and-verifying/) and [Monitoring deliveries and retries](https://illizeo.com/en/centre-aide/webhooks-monitoring-deliveries/).

## 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.

### *Similaire*
