Webhook Events
Coming soon: The Webhooks API is currently under design review. This documentation describes the target interface and may change before release. The exact event identifiers shown below are provisional and pending final confirmation.
Two kinds of data can appear in
data:- Identifiers (company, payroll cycle, employee) — always present, so you can call the matching
GETendpoint for the current, authoritative state. - The fact that triggered the event (e.g. the consumption that was just charged) — included directly when it is an immutable record: replaying or re-delivering it is harmless, since it always describes the same past fact. A computed, mutable balance (like a running total or “amount still pending”) is never embedded, since a delayed or duplicated delivery could overwrite a more recent state with a stale one — for that you always call the
GETendpoint.
Event Types at a Glance
Consumption & Payroll Cycle
Committed Expenses
Consumption & Payroll Cycle Events
employee.consumption.generated
Sent when an employee’s accumulated consumptions change because of a real new consumption (a purchase is authorized and charged, a void reverts a consumption within the same cycle, etc.). consumption describes that individual transaction — the fact that triggered the event.
Fetch the accumulated totals from GET /companies/{companyId}/employees/{employeeId}/consumptions whenever you want the current state across all benefit categories (for reconciliation, a full refresh, or simply to double-check); for most integrations, the consumption data in the event is already enough to keep your own running totals up to date.
The end-of-cycle reconciliation is not a new consumption and does not trigger this event: reconciliation only consolidates what was already reported. You are only notified when a genuine new consumption occurs.
The
period field identifies the payroll period in YYYY-MM format.consumption.sumType is expenses for a charge and withdrawn for a void/reversal — same enum as the GET endpoint.company.payroll-cycle.closed
Sent once a company’s payroll cycle is closed and its reconciliation is complete — not while reconciliation is in progress. Use this event to know when a company’s consumptions for the cycle are final.
Fetch them by calling GET /companies/{companyId}/consumptions with the closed cycle’s payroll and your preferred groupBy, categories and format options.
If a late event affecting the cycle arrives after it was closed (for example, two weeks later), the cycle is reconciled again and a new
company.payroll-cycle.closed event is emitted. Always fetch the latest state when you receive it.There is intentionally no corporation-level event: the companies of a corporation do not necessarily close their payroll cycles on the same day. If you operate at corporation level, listen to
company.payroll-cycle.closed for each company and act when all of them have closed.Committed Expense Events
Coming soon: these events are still under design review and may change before release. They supersede the single
employee.committed-expense.updated event previously sketched here: instead of one generic notification, the lifecycle of a committed expense is now split into more specific events so you always know which change happened — without needing to diff two snapshots yourself.fiscalYear and benefit category, and split into monthly committed expense payments. The employee in the event identifies the account holder. If the expense applies to a dependent instead, recipient identifies that dependent. Two levels of events exist:
- Committed expense (
employee.committed-expense.*): the aggregate for afiscalYear+categorychanged — it was requested, finished, or cancelled.committedAmountInCentsandpaidAmountInCentsare included as a snapshot at the time of the event, but the remaining pending amount is a mutable, computed balance — fetch it from theGETendpoint below rather than deriving it yourself. - Committed expense payment (
employee.committed-expense.payment.cancelled): a single monthly instalment of that committed expense was cancelled. A single instalment is an immutable record — like a regular consumption — so itspayment.amountInCentsis included directly in the event.
committedAmountInCents, paidAmountInCents, numberOfPayments and pendingPayments — from GET /committed-expenses?employeeId={employeeId}&fiscalYear={fiscalYear} (coming soon) whenever you receive an employee.committed-expense.* event and you need the authoritative, current remaining limit, rather than computing it yourself. For employee.committed-expense.payment.cancelled, the payment.amountInCents value in the notification is already enough to know the amount released by that specific cancelled instalment.
employee.committed-expense.requested
Sent when a new committed expense is created / approved.
paidAmountInCents is always present on every employee.committed-expense.* event, so you don’t need to special-case any of them. On requested it is always 0: nothing has been charged yet.recipient is available only in the aggregate committed expense events (requested, finished and cancelled). It identifies the person the committed expense applies to when that person is different from the employee. It is omitted when the committed expense applies directly to the employee, so the employee’s identifier is not duplicated. The employee.committed-expense.payment.cancelled event does not include recipient.id.employee.committed-expense.finished
Sent when the last scheduled payment of a committed expense has been executed and nothing is left pending. This is a terminal state: no further events are expected for this fiscalYear + category unless a new committed expense is requested.
employee.committed-expense.cancelled
Sent when a committed expense is cancelled / rejected as a whole, or when its remaining future payments are cancelled (a partial cancellation) — this can happen before or after some payments have already been executed.
An amount cannot be modified in place — a modification is a cancellation of the existing committed expense (this event) plus the creation of a new one (
employee.committed-expense.requested), so you receive both notifications.employee.committed-expense.payment.cancelled
Sent when a single scheduled payment is cancelled or voided without cancelling the rest of the committed expense (for example, a manual incident voids one month, or a payment is withdrawn after delivery but the remaining months are kept). payment.amountInCents contains the amount released back to the employee’s limit; the commitment itself continues for the remaining payments.
Manage Your Subscriptions
Once you know which events you need, register a subscription and pick which of these types to receive:
See the Webhooks Overview for how to set up a subscription end-to-end, verify signatures, and understand delivery semantics.