Event types & payload
The events Kua emits and the shape of each delivery.
Before you subscribe
Events and webhooks are Live-key only; authorise the selected environment and grants first. An event name describes an observation, not permission or a public endpoint to perform that action. Match the aggregate and documented outcome: a payroll-line settlement is not a general bank-withdrawal confirmation.
Envelope
Every webhook body is a JSON envelope:
{
"id": "00000000-0000-4000-8000-000000000001",
"type": "payroll.run.disbursed",
"occurredAt": "2026-07-14T10:30:00.000Z",
"aggregate": { "type": "PayrollRun", "id": "00000000-0000-4000-8000-000000000002" },
"data": { "runId": "00000000-0000-4000-8000-000000000002", "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 (continue with the last processed event’s exact occurredAt as since and id as afterId; see pagination) — 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. |
Confirm processing
The envelope above is synthetic. Verify signatures before trusting webhook bodies, deduplicate the signed id, and retain unknown event types intentionally rather than failing every retry. For the pull API, persist a paired cursor only after durable processing and reconcile late arrivals. A type absent from this introductory catalog may still be added by the API; use the live specification and observed payload contract for the key mode.
Continue to signature verification, polling or delivery recovery.