---
title: Creating and managing a webhook
description: Subscribe one of your systems to Illizeo events, hand over the signing secret, then edit, test, deactivate or delete the webhook.
url: "https://illizeo.com/en/centre-aide/webhooks-creating-and-managing/"
updated: "2026-11-05"
category: Platform / Webhooks
---

# Creating and managing a webhook

A webhook notifies one of your systems as soon as something happens in Illizeo: a hire, an approved absence, a signed document, a published shift. Illizeo then sends a signed message to the address you chose. Where an API token lets a system come and read, a webhook tells it. This article explains how to create a webhook, hand over its secret, edit it, test it, suspend it and delete it. It is for administrators.

## Before you start

- The screen is under **Settings › Manage Illizeo › Webhooks**. The entry only appears if your subscription includes webhooks (they are open during the trial period) and if one of your roles holds the “Webhooks — View” permission.
- Creating, editing, testing, deactivating or deleting a webhook, and rotating its secret, require the “Webhooks — Create / edit / delete” permission at the **Execute** level. By default, only the Administrator role holds these permissions, which are set in **Settings › Manage Employees › Employee Roles** (see [Permissions & roles](https://illizeo.com/en/docs-category/platform-en/platform-roles-permissions/)).
- These permissions are separate from the API token ones: webhooks can be entrusted without entrusting tokens.
- The receiving system must expose a public `https://` address. Setting it up is described in [Receiving and verifying a webhook](https://illizeo.com/en/centre-aide/webhooks-receiving-and-verifying/).

## The webhook list

Each row shows:

- **Webhook**: the name and the receiving address;
- **Events**: the first three subscriptions, then “+n”;
- **Last delivery**: its status and date, or **Never** (tests do not count);
- **Status**: the activation switch, marked **Failing since** when deliveries fail, or **Disabled after failures**;
- **Actions**: **View**, **Edit**, **Delete**.

The **Documentation** button, shown if you also have access to API tokens, opens the API documentation, which lists the events.

![The Settings, Manage Illizeo, Webhooks page: table of webhooks with the Webhook (name and receiving address), Events, Last delivery, Status with the activation switch, and Actions columns, Documentation and New webhook buttons](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/webhooks-creating-and-managing-01.en_.png?resize=800%2C191&quality=80&ssl=1)
Settings › Manage Illizeo › Webhooks.

## Creating a webhook

1. Click **New webhook** (or **Create the first webhook** if the list is empty).
2. **Name** (required, 100 characters at most): the system to notify, for example “Payroll software”.
3. **Receiving address**: the address that will receive the messages. It must start with `https://`; an internal network address is refused.
4. **Events** (at least one): tick events one by one, or a whole family.
5. Click **Create webhook**. It is active straight away.

Ticking a family (for example **Absences**, code `absence.*`) subscribes the webhook to all its events, including those the family gains later. Families of modules not enabled in your space do not appear. Each event is detailed in the [Webhook event catalogue](https://illizeo.com/en/centre-aide/webhooks-event-catalogue/).

![The New webhook window: Name field filled with Payroll software, Receiving address field filled with a fictitious https address and the HTTPS only help text, then the list of event families with their boxes and codes](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/webhooks-creating-and-managing-02.en_.png?resize=672%2C810&quality=80&ssl=1)
Creating a webhook.

## Handing over the signing secret

On creation, the **Signing secret** window shows the webhook's secret (it starts with `whsec_`) and a code sample under **Verifying a delivery**. The receiving system uses it to check that each message really comes from Illizeo. Copy it, send it through a secure channel to the person configuring the receiver, then click **I have saved it**.

The secret is never shown again afterwards: the webhook page only shows its beginning. If it is lost, rotate it.

## Editing, testing, rotating the secret

- **Edit** (icon in the list or button on the webhook page): the **Edit webhook** window lets you change the name, address and events, then **Save**. The secret does not change.
- **Send a test** (webhook page): immediately sends a `ping` event to the address, in a single attempt, without retries. A message says “Test delivered” with the response code, or “Test failed” with the reason. The test appears in the deliveries and does not count towards usage.
- **Rotate secret** (webhook page): the new secret is created as soon as you click, without a confirmation step, and is shown only once. The old one no longer signs anything: the receiver will reject the following messages until it has the new one. Warn the person who manages it before clicking.

## Deactivating or deleting

- **Deactivate**: switch off the toggle in the **Status** column. Nothing more is sent, and events that occur while it is deactivated are not kept aside: once reactivated, the webhook only receives new ones. Reactivating also clears the current series of failures.
- **Delete**: the **Delete** icon opens the **Delete webhook** confirmation. The receiving system is no longer notified, and this webhook's delivery log is deleted with it.

![The Delete webhook confirmation box: warning that the receiving system will no longer be notified and that the delivery log is deleted, webhook name, Cancel and Delete buttons](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/webhooks-creating-and-managing-03.en_.png?resize=448%2C206&quality=80&ssl=1)
The webhook deletion confirmation.

## Good to know

- A webhook that fails continuously for three days is deactivated automatically, and its creator notified (see [Monitoring deliveries and retries](https://illizeo.com/en/centre-aide/webhooks-monitoring-deliveries/)).
- Creations, edits, deletions, manual activations and deactivations, and secret rotations are recorded in **Settings › Manage Illizeo › User Logs**. The secret value never appears there.
- Messages mostly carry identifiers and states, never a person's name or a salary amount: for details, the receiving system reads the resource back through the API with a token (see [Creating and managing API tokens](https://illizeo.com/en/centre-aide/api-managing-tokens/)).
- Several webhooks can listen to the same event: each one gets its own message.

## FAQ

### I cannot see the “New webhook” button.

It requires the “Webhooks — Create / edit / delete” permission at the Execute level.

### Saving refuses my address.

It must start with `https://` and point to a server reachable from the internet. An address leading to an internal network is refused.

### A family I expect does not appear.

Its module is not enabled in your space: Scheduling, Annualised working time, Budget, BDESE, Swiss payroll and Flex Office only have events if the module is enabled.

### *Similaire*