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

# Webhook event catalog

> Every partner webhook event, grouped by resource, with what it means and which ones to subscribe to.

Every event Stableyard delivers to partner endpoints, grouped the way `GET /v2/partners/config` groups them. Each event is a prompt to read the resource it names. The envelope and headers are on [Webhooks](/webhooks#what-a-delivery-contains).

## Read the catalog at runtime

`GET /v2/partners/config` returns the machine-readable catalog for the current deployment under `capabilities.webhooks`, along with the recommended subset and the event groups:

```json theme={null}
"webhooks": {
  "supportedEvents": ["account.created", "account.updated", "bank_funding.completed", "…"],
  "recommendedEvents": ["account.created", "account.updated", "bank_funding.completed", "…"],
  "eventGroups": [
    { "id": "payments", "label": "Payments", "events": ["payment.created", "payment.requires_action", "…"] }
  ]
}
```

New partner events are added over time, so your consumer must ignore unknown event names safely rather than throwing. The **Recommended** column below marks the events in `recommendedEvents`.

| Group `id` | Events | Section |
| - | - | - |
| `payments` | 15 | [Payment events](#payment-events) |
| `deposits` | 5 | [Deposit events](#deposit-events) |
| `bank_funding` | 2 | [Bank funding events](#bank-funding-events) |
| `accounts` | 2 | [Account events](#account-events) |
| `kyc` | 9 | [KYC events](#kyc-events) |
| `compliance` | 5 | [Regulated capability events](#regulated-capability-events) |
| `smart_wallets` | 3 | [Smart-wallet events](#smart-wallet-events) |
| `vaults` | 6 | [Vault events](#vault-events) |

<Note>
  Internal state-machine events are kept for Stableyard's own audit and reconciliation and are never delivered to partner endpoints. That includes the intermediate deposit states (`deposit.confirming`, `deposit.settling`, `deposit.retry_scheduled`) and the whole internal payment-session, option, settlement, fee-payout and refund worker lifecycle. If you need finer-grained deposit status than `detected`, `settled`, `reversed` and `requires_intervention`, poll the deposit instead.
</Note>

## Payment events

| Event | Meaning | Recommended |
| - | - | - |
| `payment.created` | Stableyard created the canonical Payment. No payer funds or outgoing broadcast is implied | No |
| `payment.requires_action` | The payer, account owner or partner must complete the returned action | No |
| `payment.processing` | Provider processing or an outgoing transaction is in progress | Yes |
| `payment.accepted` | Receive-payment funds were independently verified. Settlement may still be pending | Yes |
| `payment.refund_pending` | One or more linked refunds were created or broadcast and still require final evidence | Yes |
| `payment.partially_refunded` | Confirmed linked refunds cover only part of the refundable Payment amount | Yes |
| `payment.refunded` | Confirmed linked refunds cover the full refundable Payment amount | Yes |
| `payment.succeeded` | Terminal success after final settlement or outgoing confirmation | Yes |
| `payment.expired` | An unfunded Payment reached terminal expiry. Stop polling; start a new Payment for a new attempt | Yes |
| `payment.cancelled` | Terminal cancellation before incompatible financial processing began | Yes |
| `payment.failed` | Terminal failure with no unresolved custody obligation | Yes |
| `payment.requires_intervention` | Automated processing stopped safely for operations review. The financial `status` is preserved; inspect `operationalState` and `operationalReasonCode` | Yes |
| `payment.duplicate_received` | A second valid funding transfer arrived after another option had already won. Recovery is required | Yes |
| `payment.late_received` | Valid funds arrived after the Payment could be accepted normally. Recovery is required | Yes |
| `payment.settlement_returned` | A previously broadcast settlement was returned or rejected downstream | Yes |

Off-ramp success payloads carry the delivered amount at its exact precision: `deliveredAmount` (a decimal string), `deliveredAmountAtomic`, `deliveredAssetCode` and `deliveredAssetDecimals`. An exact-input USD receipt can keep six decimal places, so scale by `deliveredAssetDecimals` rather than assuming cents. Older success events without a precision field keep their original units; use their decimal `deliveredAmount` when present. Settlement-return payloads likewise pair `amountAtomic` with `assetDecimals`.

Events are additive and may be delivered more than once. Fetch `GET /v2/payments/{paymentId}` as the current source of truth rather than reconstructing state from delivery order. Reconcile financial `status`, `operationalState` and `refundSummary` independently.

A payment payload carries the fields that identify the payment and its state at the event, such as `paymentId`, `intent`, `status`, `stage`, `operationalState`, `operationalReasonCode` and `statusVersion`. Keep the highest `statusVersion` you have seen and discard anything lower. See [Reconciliation](/payments/reconciliation#survive-duplicates-and-reordering).

For account-bound `payment.*` events, `payload.accountId` identifies the account whose app environment owns that delivery. It is the sender on a send Payment and the recipient on a receive Payment, not a generic counterparty ID, and the payload repeats it as `senderAccountId` or `receiverAccountId`. Public wallet Payments may omit it. Use `paymentId` as the durable financial identity, and fetch the Payment when the event does not carry enough context for your ledger or interface.

## Deposit events

| Event | Meaning | Recommended |
| - | - | - |
| `deposit.detected` | Funds first observed. Carries source `chainId`, `tokenAddress`, `depositId`, `depositAddressId`, `transactionId` when available, `txHash` and `amountAtomic` | Yes |
| `deposit.settled` | Final settlement complete. This is the completed-deposit event. Stableyard does not emit `deposit.completed`. Carries `depositId`, `amountAtomic`, `chainId`, `tokenAddress` and `assetSymbol` | Yes |
| `deposit.reversed` | Stableyard invalidated a previously settled accounting record. **This does not imply an on-chain clawback.** See [Hold](/capabilities#hold) | Yes |
| `deposit.requires_intervention` | Automation needs manual review | Yes |
| `deposit.failed` | Reserved for terminal failures | No |

Read `GET /v2/accounts/{accountId}/deposits` for the current state of each deposit. See [Deposit addresses](/concepts/deposit-addresses).

## Bank funding events

Sent for an on-ramp bank account. The payload carries `accountId`, `onrampBankAccountId`, `transactionId`, `status`, the USD and stablecoin amounts, and `destinationTxHash` when already known. It never contains bank details.

| Event | Meaning | Recommended |
| - | - | - |
| `bank_funding.completed` | An incoming bank transfer was converted and delivered to the wallet. Read the funding facility's transactions for amounts and the on-chain hash | Yes |
| `bank_funding.failed` | An incoming bank transfer could not be converted | Yes |

Read `GET /v2/accounts/{accountId}/onramp-bank-accounts/{onrampBankAccountId}/transactions` for these funding transactions. They use their own transaction identity; an inbound transfer into a standing funding account does not require a new receive Payment.

See [On-ramp accounts](/concepts/on-ramp-accounts).

## Account events

| Event | Meaning | Recommended |
| - | - | - |
| `account.created` | A partner-created account was created. Public wallet Payments do not create accounts and do not emit this event | Yes |
| `account.updated` | Material account configuration changed, such as linked wallets, the handle, payment acceptance, the display profile, settlement configuration, the email or a linked bank. Fetch the account for the canonical record | Yes |

## KYC events

| Event | Meaning | Recommended |
| - | - | - |
| `kyc.session_created` | An identity verification session was created | No |
| `kyc.updated` | The identity verification status changed. Fetch the resource for the canonical state | No |
| `partner_kyc.requires_information` | Partner-managed KYC is missing required customer information | No |
| `partner_kyc.information_submitted` | The requested information was submitted. This is not approval | No |
| `partner_kyc.ready_to_submit` | There is enough validated information to submit | No |
| `partner_kyc.submitted` | Stableyard submitted the partner-managed KYC record | No |
| `partner_kyc.approved` | The submission was approved | No |
| `partner_kyc.rejected` | The submission was rejected | No |
| `offramp_partner_account.linked` | Stableyard linked the account to the relationship used by an External QR or External Bank payout | No |

For `kyc.*`, read `GET /v2/accounts/{accountId}/kyc`. See [Individual KYC](/concepts/individual-kyc).

## Regulated capability events

| Event | Meaning | Recommended |
| - | - | - |
| `compliance.action_required` | The account holder must complete or resume the current hosted compliance action. Fetch account capabilities for the current one-time URL | Yes |
| `compliance.submitted` | Consent and required evidence were durably accepted and one onboarding attempt was queued. This is not approval | No |
| `compliance.approved` | The regulated relationship is active. Fetch account capabilities before enabling the feature | Yes |
| `compliance.rejected` | The regulated relationship was rejected. Do not retry onboarding automatically | Yes |
| `compliance.requires_intervention` | Automated onboarding or reconciliation stopped for operations review | Yes |

See [Capability activation](/concepts/capability-activation) and [Business KYB](/concepts/business-verification).

## Smart-wallet events

| Event | Meaning | Recommended |
| - | - | - |
| `smart_wallet.active` | Deployment and required policy verification completed | No |
| `smart_wallet.deployment_failed` | Deployment reached a terminal failure | No |
| `smart_wallet.requires_intervention` | Provisioning or policy verification requires manual review | No |

## Vault events

| Event | Meaning | Recommended |
| - | - | - |
| `vault.policy_active` | The requested Vault policy is verified as active | No |
| `vault.failed` | Vault provisioning reached a terminal failure | No |
| `vault.funding_posted` | A direct Vault funding transfer was verified and posted to the financial ledger | No |
| `vault.funding_requires_intervention` | A Vault funding transfer requires manual evidence or accounting review | No |
| `vault.yield_supply_settled` | A yield-supply operation was confirmed on-chain | No |
| `vault.yield_supply_failed` | A yield-supply operation failed | No |

See [Treasury settlement](/settlement/treasury-settlement).

## Related

<CardGroup cols={2}>
  <Card title="Webhooks overview" icon="bolt" href="/webhooks">
    Create an endpoint and choose what it subscribes to.
  </Card>

  <Card title="Verifying signatures" icon="shield-check" href="/webhooks/verifying-signatures">
    Check each delivery before you trust it.
  </Card>

  <Card title="Status codes" icon="signal" href="/status-codes">
    Payment, deposit and refund states, and which are terminal.
  </Card>

  <Card title="Reconciliation" icon="scale-balanced" href="/payments/reconciliation">
    Match events to your ledger through duplicates and reordering.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.