Subscribe an endpoint of your information system to HR events: Illizeo sends it a signed message each time one happens.
What a webhook does #
An API token lets a third-party tool read Illizeo; a webhook notifies it. When an event happens, Illizeo sends a JSON POST request to the https endpoint you declared. Your system no longer needs to poll the API.
Available events #
| Family | Events |
|---|---|
| Employees | employee.created, employee.updated, employee.contract_ended |
| Absences | absence.requested, absence.approved, absence.rejected, absence.cancelled |
| Time and attendance | attendance.day_closed |
| Documents | document.uploaded, document.generated |
| Electronic signatures | signature.completed, signature.declined, signature.cancelled |
| Scheduled exports | export.ready |
A subscription can listen to one event, a whole family (employee.*) or all events (*).
Create a subscription #
-
Open the screen. Settings › Manage Illizeo › Webhooks. You need the permission to manage webhooks; the view permission is enough to see the list and the log.
-
Declare the endpoint. Give a name and an https address. Internal network addresses are refused.
-
Choose the events. One event, a family or everything.
-
Keep the secret. It is used to verify the signature and can be rotated at any time.
-
Send a test. The button sends a
pingmessage and shows your server’s response.
The message you receive #
The body contains id (unique event ID), event, occurred_at, tenant and data. data only carries identifiers and statuses: never a social security number, a salary or an attachment. For the details, your system reads the API with its token.
Headers: Illizeo-Event, Illizeo-Event-Id, Illizeo-Delivery and Illizeo-Signature.
Verify the signature #
-
Read the header.
Illizeo-Signature: t=<unix timestamp>,v1=<signature>. -
Recompute. HMAC-SHA256, with the subscription secret, of the string
<t>.<raw body received>, in hex. Use the raw body, not re-encoded JSON. -
Compare in constant time with
v1, and reject an old timestamp (5 minutes recommended) to block replays. -
De-duplicate on
Illizeo-Event-Id: a retry can deliver the same event twice.
Delivery, retries and log #
| Rule | Value |
|---|---|
| When it is sent | After the record is committed: a cancelled change sends nothing |
| Timeout per attempt | 10 seconds; any 2xx response counts as received; redirects are not followed |
| Retries | 6 attempts: immediately, then after 1 min, 5 min, 30 min, 2 h and 12 h |
| After the last one | The delivery is abandoned; it can be retried by hand from the log |
| Continuous failures | After 72 hours, the subscription is deactivated and its creator notified |
| Log | Response code, duration and error of every delivery, kept for 30 days |
FAQ #
Are webhooks included in my subscription?
They depend on your subscription. If the Webhooks screen does not appear, contact us.
Can a webhook block an HR entry?
No. Sending is queued, after the record is saved. A slow or failing server never slows down or cancels anything in Illizeo.
Can I connect Zapier or Make?
Yes, with an “incoming webhook” trigger: declare its https address as a subscription. Verify the signature if the tool allows it.
What about the Approve button in Slack?
That works the other way round: Slack calls Illizeo. It is not a configurable webhook, it is an internal part of the Slack connector.
