Webhook event catalog

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.

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:

"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
`deposits`	5	Deposit events
`bank_funding`	2	Bank funding events
`accounts`	2	Account events
`kyc`	9	KYC events
`compliance`	5	Regulated capability events
`smart_wallets`	3	Smart-wallet events
`vaults`	6	Vault events

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.

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

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.

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.

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 and Business KYB.

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.

Webhooks overview

Create an endpoint and choose what it subscribes to.

Verifying signatures

Check each delivery before you trust it.

Status codes

Payment, deposit and refund states, and which are terminal.

Reconciliation

Match events to your ledger through duplicates and reordering.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Webhook event catalog

Read the catalog at runtime

Payment events

Deposit events

Bank funding events

Account events

KYC events

Regulated capability events

Smart-wallet events

Vault events

Webhooks overview

Verifying signatures

Status codes

Reconciliation

​Read the catalog at runtime

​Payment events

​Deposit events

​Bank funding events

​Account events

​KYC events

​Regulated capability events

​Smart-wallet events

​Vault events

​Related

Webhooks overview

Verifying signatures

Status codes

Reconciliation

Read the catalog at runtime

Payment events

Deposit events

Bank funding events

Account events

KYC events

Regulated capability events

Smart-wallet events

Vault events

Related