Event types & payload

Envelope

Every webhook body is a JSON envelope:

{
  "id": "0c2f…",
  "type": "payroll.run.disbursed",
  "occurredAt": "2026-07-14T10:30:00.000Z",
  "aggregate": { "type": "PayrollRun", "id": "8ab1…" },
  "data": { "runId": "8ab1…", "settled": 42, "status": "Disbursed" }
}

id — the event’s unique id. Dedupe on this.

type — the event type (below). Subscribe to specific types, or * for all.

occurredAt — ISO-8601 UTC timestamp.

aggregate — the entity the event is about.

data — event-specific fields.

The same objects are also queryable at GET /v1/events (poll by since=) — the webhook is just the push version of that timeline.

Event catalog

Payroll

Type	When
`payroll.run.hr_approved`	A run was approved by HR.
`payroll.run.disbursement_started`	Disbursement began.
`payroll.run.disbursed`	Every line settled.
`payroll.run.partially_disbursed`	Some lines failed.
`payroll.line.settled`	An employee was paid.
`payroll.line.failed`	A line failed to disburse.
`payroll.funding.requested` / `.approved` / `.rejected`	Funding-approval flow.

People

Type	When
`employee.created`	An employee was added.
`employee.updated`	An employee’s record changed.
`employee.offboarded` / `employee.reinstated`	Employment status changed.
`salary_structure.set`	A salary structure was set/updated.

Money & wallets

Type	When
`company.wallet.funded`	The company wallet was funded.
`company.va.assigned`	A funding virtual account was issued.
`employee.wallet.funded`	Net pay landed in an employee wallet.
`employee.withdrawal.settled` / `.failed`	A worker withdrawal resolved.
`salary_advance.requested` / `.approved` / `.rejected`	Advance lifecycle.

Workspace & compliance

Type	When
`workspace.activation.approved` / `.rejected`	KYB review decision.
`deduction.remittance.submitted` / `.confirmed` / `.failed`	Deduction remittance.
`leave_request.submitted` / `.approved` / `.rejected`	Leave lifecycle.

New event types are added over time. Handle unknown type values gracefully — ignore what you don’t recognise rather than erroring.

​Envelope

​Event catalog

Envelope

Event catalog