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

# Webhook event types and payload reference

> Complete list of Yoshi webhook event types with example payloads for accounts, transactions, balances, investments, scores, and income.

Events use a `resource.action` naming convention. Each event is delivered as a JSON object with the standard [event envelope](/webhooks/overview#event-envelope).

You can subscribe to specific event types when [creating an endpoint](/webhooks/management#create-an-endpoint), or receive all events by leaving the filter empty.

## Account events

Account events fire when a user's linked financial accounts change.

<AccordionGroup>
  <Accordion title="account.connected">
    A new financial account was linked.

    Fired when a user successfully connects a financial institution through the Yoshi link flow.

    ```json theme={null}
    {
      "id": "evt_9YnQRSnLE4FrI3XmYdSTzUHfCU",
      "type": "account.connected",
      "created_at": "2026-04-10T12:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "id": "acc_xyz789",
        "name": "Chase Checking (...4521)",
        "type": "depository",
        "subtype": "checking",
        "institution_name": "Chase"
      }
    }
    ```

    | Field                   | Type             | Description                                                             |
    | ----------------------- | ---------------- | ----------------------------------------------------------------------- |
    | `data.id`               | `string`         | Account ID. Use with `GET /accounts` to fetch full details.             |
    | `data.name`             | `string`         | Display name with masked account number.                                |
    | `data.type`             | `string`         | Account type: `depository`, `credit`, `investment`, `loan`, or `other`. |
    | `data.subtype`          | `string \| null` | Account subtype, e.g. `checking`, `savings`, `credit card`.             |
    | `data.institution_name` | `string \| null` | Name of the financial institution.                                      |
  </Accordion>

  <Accordion title="account.disconnected">
    Account access was revoked.

    Fired when a financial account is disconnected — either by the user unlinking it or due to an institution-side error that revoked access.

    ```json theme={null}
    {
      "id": "evt_7XmPQRnKE3EqH2WlXcRTzTGeBU",
      "type": "account.disconnected",
      "created_at": "2026-04-10T16:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "id": "acc_xyz789",
        "name": "Chase Checking (...4521)",
        "reason": "ITEM_LOGIN_REQUIRED"
      }
    }
    ```

    | Field         | Type             | Description                               |
    | ------------- | ---------------- | ----------------------------------------- |
    | `data.id`     | `string`         | Account ID.                               |
    | `data.name`   | `string`         | Display name of the disconnected account. |
    | `data.reason` | `string \| null` | Reason for disconnection, if available.   |
  </Accordion>

  <Accordion title="account.updated">
    Account metadata changed.

    Fired when an account's name, type, or other metadata changes during a sync.

    ```json theme={null}
    {
      "id": "evt_5WkNOPmJD2DpG1VkWbQSySFdBT",
      "type": "account.updated",
      "created_at": "2026-04-10T13:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "id": "acc_xyz789",
        "name": "Chase Savings (...4521)",
        "type": "depository",
        "subtype": "savings"
      }
    }
    ```

    | Field          | Type             | Description           |
    | -------------- | ---------------- | --------------------- |
    | `data.id`      | `string`         | Account ID.           |
    | `data.name`    | `string`         | Updated display name. |
    | `data.type`    | `string`         | Account type.         |
    | `data.subtype` | `string \| null` | Account subtype.      |
  </Accordion>
</AccordionGroup>

## Transaction events

Transaction events fire when transactions are synced from financial institutions.

<AccordionGroup>
  <Accordion title="transaction.created">
    New transactions synced from an institution.

    Fired after new transactions are persisted during a transaction sync. The payload contains transaction IDs — fetch full details via `GET /transactions`.

    ```json theme={null}
    {
      "id": "evt_2KWPBQMnRE2EqH9WlXbQTzSGeAT",
      "type": "transaction.created",
      "created_at": "2026-04-10T14:30:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_xyz789",
        "transaction_ids": ["txn_abc123", "txn_def456", "txn_ghi789"],
        "count": 3
      }
    }
    ```

    | Field                  | Type       | Description                                  |
    | ---------------------- | ---------- | -------------------------------------------- |
    | `data.account_id`      | `string`   | The account that the transactions belong to. |
    | `data.transaction_ids` | `string[]` | IDs of the new transactions.                 |
    | `data.count`           | `number`   | Number of new transactions in this event.    |
  </Accordion>

  <Accordion title="transaction.updated">
    Transaction details were modified.

    Fired when existing transactions are re-categorized, have merchant names corrected, or are otherwise updated by the institution.

    ```json theme={null}
    {
      "id": "evt_4VjMNOlIC1CnF0UjVaPS1REdAS",
      "type": "transaction.updated",
      "created_at": "2026-04-10T15:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_xyz789",
        "transaction_ids": ["txn_abc123"],
        "count": 1
      }
    }
    ```

    | Field                  | Type       | Description                                  |
    | ---------------------- | ---------- | -------------------------------------------- |
    | `data.account_id`      | `string`   | The account that the transactions belong to. |
    | `data.transaction_ids` | `string[]` | IDs of the updated transactions.             |
    | `data.count`           | `number`   | Number of updated transactions.              |
  </Accordion>

  <Accordion title="transaction.removed">
    Transactions were removed by the institution.

    Fired when an institution retroactively removes transactions — for example, when a pending transaction is voided.

    ```json theme={null}
    {
      "id": "evt_6XoPRSnME4GsJ2YmZeUTzVIfDW",
      "type": "transaction.removed",
      "created_at": "2026-04-10T16:30:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_xyz789",
        "transaction_ids": ["txn_abc123"],
        "count": 1
      }
    }
    ```

    | Field                  | Type       | Description                                    |
    | ---------------------- | ---------- | ---------------------------------------------- |
    | `data.account_id`      | `string`   | The account that the transactions belonged to. |
    | `data.transaction_ids` | `string[]` | IDs of the removed transactions.               |
    | `data.count`           | `number`   | Number of removed transactions.                |
  </Accordion>
</AccordionGroup>

## Balance events

<AccordionGroup>
  <Accordion title="balance.updated">
    Account balance was refreshed.

    Fired when an account's current or available balance changes during a sync.

    ```json theme={null}
    {
      "id": "evt_8XmPQRnKE3EqH2WlXcRTzTGeBS",
      "type": "balance.updated",
      "created_at": "2026-04-10T15:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_xyz789",
        "current": 4523.17,
        "available": 4423.17,
        "currency": "USD"
      }
    }
    ```

    | Field             | Type             | Description                                               |
    | ----------------- | ---------------- | --------------------------------------------------------- |
    | `data.account_id` | `string`         | Account ID.                                               |
    | `data.current`    | `number \| null` | Current balance.                                          |
    | `data.available`  | `number \| null` | Available balance (may differ from current due to holds). |
    | `data.currency`   | `string`         | ISO 4217 currency code.                                   |
  </Accordion>
</AccordionGroup>

## Investment events

<AccordionGroup>
  <Accordion title="investment.holdings_updated">
    Investment holdings data was refreshed.

    Fired after an investment account sync updates holdings positions.

    ```json theme={null}
    {
      "id": "evt_3UiLMNkHB0BmE9TiUZOR0QDcZR",
      "type": "investment.holdings_updated",
      "created_at": "2026-04-10T09:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_inv456",
        "holding_count": 12
      }
    }
    ```

    | Field                | Type     | Description                                       |
    | -------------------- | -------- | ------------------------------------------------- |
    | `data.account_id`    | `string` | Investment account ID.                            |
    | `data.holding_count` | `number` | Number of holdings in the account after the sync. |
  </Accordion>

  <Accordion title="investment.transaction_created">
    New investment transactions detected.

    Fired when new investment transactions (buys, sells, dividends) are synced.

    ```json theme={null}
    {
      "id": "evt_1ThKLMjGA9AlD8ShTYNQ9PCbYQ",
      "type": "investment.transaction_created",
      "created_at": "2026-04-10T09:30:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "account_id": "acc_inv456",
        "transaction_ids": ["itxn_abc123"],
        "count": 1
      }
    }
    ```

    | Field                  | Type       | Description                             |
    | ---------------------- | ---------- | --------------------------------------- |
    | `data.account_id`      | `string`   | Investment account ID.                  |
    | `data.transaction_ids` | `string[]` | IDs of the new investment transactions. |
    | `data.count`           | `number`   | Number of new investment transactions.  |
  </Accordion>
</AccordionGroup>

## Score events

<AccordionGroup>
  <Accordion title="score.updated">
    Financial health scores were recalculated.

    Fired after a user's financial health scores are recomputed based on new data.

    ```json theme={null}
    {
      "id": "evt_0SgJKLiF98ZkC7RgSXMP8OBaXP",
      "type": "score.updated",
      "created_at": "2026-04-10T10:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "user_id": "usr_abc123",
        "score_types": ["recovery", "capacity", "baseline", "composite"]
      }
    }
    ```

    | Field              | Type       | Description                          |
    | ------------------ | ---------- | ------------------------------------ |
    | `data.user_id`     | `string`   | User whose scores were updated.      |
    | `data.score_types` | `string[]` | Which score types were recalculated. |
  </Accordion>
</AccordionGroup>

## Income events

<AccordionGroup>
  <Accordion title="income.detected">
    Income stream identified or updated.

    Fired when income analysis detects or updates recurring income streams for a user.

    ```json theme={null}
    {
      "id": "evt_BRfHIKhE87YjB6QfRWLO7NAzWO",
      "type": "income.detected",
      "created_at": "2026-04-10T11:00:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "user_id": "usr_abc123",
        "stream_count": 2
      }
    }
    ```

    | Field               | Type     | Description                        |
    | ------------------- | -------- | ---------------------------------- |
    | `data.user_id`      | `string` | User whose income was analyzed.    |
    | `data.stream_count` | `number` | Number of income streams detected. |
  </Accordion>
</AccordionGroup>

## Recurring events

<AccordionGroup>
  <Accordion title="recurring.updated">
    Recurring transaction streams were re-analyzed.

    Fired when Yoshi re-evaluates a user's recurring transactions (subscriptions, bills, regular transfers).

    ```json theme={null}
    {
      "id": "evt_CQeGHJgD76XiA5PeQVKN6MZyVN",
      "type": "recurring.updated",
      "created_at": "2026-04-10T11:30:00.000Z",
      "api_version": "2026-04-10",
      "data": {
        "user_id": "usr_abc123",
        "stream_count": 8
      }
    }
    ```

    | Field               | Type     | Description                                 |
    | ------------------- | -------- | ------------------------------------------- |
    | `data.user_id`      | `string` | User whose recurring streams were analyzed. |
    | `data.stream_count` | `number` | Number of recurring streams detected.       |
  </Accordion>
</AccordionGroup>