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).
• 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.

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.

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.

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.

Good to know #

• A webhook that fails continuously for three days is deactivated automatically, and its creator notified (see Monitoring deliveries and retries).
• 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).
• 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.