> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuahr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event types & payload

> The events Kua emits and the shape of each delivery.

## Envelope

Every webhook body is a JSON envelope:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.     |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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.                    |
  </Accordion>

  <Accordion title="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.      |
  </Accordion>
</AccordionGroup>

<Note>
  New event types are added over time. Handle unknown `type` values gracefully —
  ignore what you don't recognise rather than erroring.
</Note>