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

# Event catalog

> Every event Kira sends, grouped by the resource it belongs to.

Branch on the `event` name. The tables below group them by resource, which is also how the `data` payload is shaped.

## Sub-client

| Event                           | Sent when                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `user.created`                  | The sub-client record exists                                                    |
| `user.updated`                  | The record changed                                                              |
| `user.status_changed`           | Every lifecycle transition, carrying `previous_status` and `new_status`         |
| `user.verification.accepted`    | Verification approved                                                           |
| `user.verification.failed`      | Verification terminally declined, with `data.reasons[]`                         |
| `user.liveness_completed`       | A liveness check reached a result, with `data.result` and the person it was for |
| `user.document.download.failed` | A document supplied by URL could not be fetched                                 |

<Warning>
  **Subscribe to `user.status_changed`.** It is the one event that fires on every transition, and the reasons on `user.verification.failed` exist nowhere else — no read of the sub-client returns them.
</Warning>

## Virtual account and deposits

| Event                                          | Sent when                                                       |
| ---------------------------------------------- | --------------------------------------------------------------- |
| `virtual_account.created`                      | The account exists and is still being opened                    |
| `virtual_account.activated`                    | The account can receive money. **The funds-ready signal**       |
| `virtual_account.deposit_funds_received`       | Money detected                                                  |
| `virtual_account.deposit_scheduled`            | A deposit is scheduled to arrive                                |
| `virtual_account.deposit_funds_in_transit`     | On its way                                                      |
| `virtual_account.deposit_funds_in_destination` | Credited                                                        |
| `virtual_account.deposit_in_review`            | Under review                                                    |
| `virtual_account.deposit_funds_refunded`       | Returned to the sender                                          |
| `virtual_account.deposit_funds_failed`         | Settlement did not finish, with `failure_reason`                |
| `virtual_account.microdeposit_funds_received`  | A sub-dollar verification micro-deposit, not a customer payment |

Watch `virtual_account.deposit_funds_received` rather than the account balance: it is the signal that behaves the same on every rail.

## Payouts

| Event                     | Resulting status                                             |
| ------------------------- | ------------------------------------------------------------ |
| `payout.created`          | `CREATED`                                                    |
| `payout.pending`          | `PENDING`                                                    |
| `payout.processing`       | `PROCESSING`                                                 |
| `payout.completed`        | `COMPLETED`                                                  |
| `payout.failed`           | `FAILED`                                                     |
| `payout.returned`         | `FAILED`, returned by the receiving bank                     |
| `payout.expired`          | A crypto payout was not funded in time                       |
| `payout.deposit_received` | No status change — a crypto-funded payout's funding was seen |
| `payout.status_changed`   | Carries `status` and `previous_status`                       |

<Warning>
  **Subscribe to `payout.status_changed`.** `IN_REVIEW` and `KYT_PENDING` reach you on it and on nothing else, so a handler subscribed only to the named events sees a payout leave `PROCESSING` and never learns where it went.
</Warning>

## Requests for information

| Event               | Sent when                                                       |
| ------------------- | --------------------------------------------------------------- |
| `rfi.raised`        | A new request was raised against one of your sub-clients        |
| `rfi.item_returned` | One item's answer was not accepted and is being asked for again |
| `rfi.resolved`      | Satisfied — whatever it was blocking is unblocked               |
| `rfi.not_resolved`  | Closed unsatisfied, with a `resolution_reason`                  |

The item is the unit: a request can carry several, each answered and each returned on its own. Answering one sends you nothing — your own answers are not news.

A URL with no event filter receives `rfi.*` along with everything else. A URL with a filter receives it only if the filter names these events. [Webhooks overview](/webhooks/overview) has the subscription rules.

## Comparing values

Compare event names and status values **case-insensitively** rather than matching exact strings. The tables show them as they arrive.