Webhook event types and payload reference

Events use a resource.action naming convention. Each event is delivered as a JSON object with the standard event envelope. You can subscribe to specific event types when creating an endpoint, or receive all events by leaving the filter empty.

Account events

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

account.connected

A new financial account was linked.Fired when a user successfully connects a financial institution through the Yoshi link flow.

{
  "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.

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.

{
  "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.

account.updated

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

{
  "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.

Transaction events

Transaction events fire when transactions are synced from financial institutions.

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.

{
  "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.

transaction.updated

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

{
  "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.

transaction.removed

Transactions were removed by the institution.Fired when an institution retroactively removes transactions — for example, when a pending transaction is voided.

{
  "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.

Balance events

balance.updated

Account balance was refreshed.Fired when an account’s current or available balance changes during a sync.

{
  "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.

Investment events

investment.holdings_updated

Investment holdings data was refreshed.Fired after an investment account sync updates holdings positions.

{
  "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.

investment.transaction_created

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

{
  "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.

Score events

score.updated

Financial health scores were recalculated.Fired after a user’s financial health scores are recomputed based on new data.

{
  "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.

Income events

income.detected

Income stream identified or updated.Fired when income analysis detects or updates recurring income streams for a user.

{
  "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.

Recurring events

recurring.updated

Recurring transaction streams were re-analyzed.Fired when Yoshi re-evaluates a user’s recurring transactions (subscriptions, bills, regular transfers).

{
  "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.

​Account events

​Transaction events

​Balance events

​Investment events

​Score events

​Income events

​Recurring events