diff --git a/docs.json b/docs.json
index 1a46808e..819c33eb 100644
--- a/docs.json
+++ b/docs.json
@@ -46,7 +46,18 @@
"pages": [
"v2/guides/webhooks-callbacks/introduction",
"v2/guides/webhooks-callbacks/set-up-endpoint",
- "v2/guides/webhooks-callbacks/webhook-event-type"
+ "v2/guides/webhooks-callbacks/webhook-event-type",
+ "v2/guides/webhooks-callbacks/transaction-webhook-payload-examples",
+ "v2/guides/webhooks-callbacks/transaction-field-dictionary",
+ "v2/guides/webhooks-callbacks/tss-request-webhook-payload-examples",
+ "v2/guides/webhooks-callbacks/tss-request-field-dictionary",
+ "v2/guides/webhooks-callbacks/wallet-address-webhook-payload-examples",
+ "v2/guides/webhooks-callbacks/wallet-address-field-dictionary",
+ "v2/guides/webhooks-callbacks/token-chain-webhook-payload-examples",
+ "v2/guides/webhooks-callbacks/token-chain-field-dictionary",
+ "v2/guides/webhooks-callbacks/balance-update-webhook-payload-examples",
+ "v2/guides/webhooks-callbacks/balance-update-field-dictionary",
+ "v2/guides/webhooks-callbacks/subscription-scenarios"
]
},
{
@@ -858,7 +869,18 @@
"pages": [
"v2_cn/guides/webhooks-callbacks/introduction",
"v2_cn/guides/webhooks-callbacks/set-up-endpoint",
- "v2_cn/guides/webhooks-callbacks/webhook-event-type"
+ "v2_cn/guides/webhooks-callbacks/webhook-event-type",
+ "v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples",
+ "v2_cn/guides/webhooks-callbacks/transaction-field-dictionary",
+ "v2_cn/guides/webhooks-callbacks/tss-request-webhook-payload-examples",
+ "v2_cn/guides/webhooks-callbacks/tss-request-field-dictionary",
+ "v2_cn/guides/webhooks-callbacks/wallet-address-webhook-payload-examples",
+ "v2_cn/guides/webhooks-callbacks/wallet-address-field-dictionary",
+ "v2_cn/guides/webhooks-callbacks/token-chain-webhook-payload-examples",
+ "v2_cn/guides/webhooks-callbacks/token-chain-field-dictionary",
+ "v2_cn/guides/webhooks-callbacks/balance-update-webhook-payload-examples",
+ "v2_cn/guides/webhooks-callbacks/balance-update-field-dictionary",
+ "v2_cn/guides/webhooks-callbacks/subscription-scenarios"
]
},
{
@@ -1598,4 +1620,4 @@
"destination": "https://www.cobo.com/payments/cn/guides/overview"
}
]
-}
\ No newline at end of file
+}
diff --git a/v2/guides/webhooks-callbacks/balance-update-field-dictionary.mdx b/v2/guides/webhooks-callbacks/balance-update-field-dictionary.mdx
new file mode 100644
index 00000000..d0ad7317
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/balance-update-field-dictionary.mdx
@@ -0,0 +1,32 @@
+---
+title: "Balance update payload field dictionary"
+lang: "en"
+description: "Definitions and trigger behavior for BalanceUpdateInfo webhook payload fields."
+sidebarTitle: "Balance update field dictionary"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page defines high-signal fields and trigger behavior for `BalanceUpdateInfo` webhook events.
+
+### Trigger behavior
+
+Both balance update event types share the same payload shape. Which event type is emitted — `wallet.mpc.balance.updated` or `wallet.web3.balance.updated` — depends on the wallet type that triggered the balance change.
+
+The event fires when Cobo's chain-scanning and balance-refresh pipeline detects a new or changed on-chain balance. It is not a fixed periodic reconciliation job, and it is not gated on transaction-ledger completion.
+
+### Field dictionary
+
+| Field | Description |
+|-------|-------------|
+| `token_id` | The token or currency whose balance changed. |
+| `address` | The on-chain address whose balance was refreshed. |
+| `wallet_uuid` | The wallet identifier for this balance payload. This field is named `wallet_uuid`, not `wallet_id`, unlike Transaction and Addresses payloads. |
+| `updated_timestamp` | The time when the balance update was recorded. |
+| `balance.total` | Total balance for the token at the address. Required by the `Balance` schema. |
+| `balance.available` | Balance currently available for use. Required by the `Balance` schema. |
+| `balance.pending` | Balance pending final availability. |
+| `balance.locked` | Balance locked by platform or workflow constraints. |
+| `balance.frozen` | Balance frozen by compliance or risk controls. |
diff --git a/v2/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx b/v2/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx
new file mode 100644
index 00000000..403b5bb0
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx
@@ -0,0 +1,30 @@
+---
+title: "Balance update webhook payload examples"
+lang: "en"
+description: "Full JSON examples of BalanceUpdateInfo webhook event payloads."
+sidebarTitle: "Balance update payload examples"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page shows complete `BalanceUpdateInfo` payloads as delivered in `wallet.mpc.balance.updated` and `wallet.web3.balance.updated` webhook events. For the event list, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+
+`wallet.mpc.balance.updated` and `wallet.web3.balance.updated` use the identical schema and differ only in which wallet type triggered the event.
+
+```json
+{
+ "token_id": "ETH_USDT",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "updated_timestamp": 1751328600000,
+ "balance": {
+ "total": "1250.50",
+ "available": "1200.00",
+ "pending": "25.50",
+ "locked": "20.00",
+ "frozen": "5.00"
+ }
+}
+```
diff --git a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
index 4153a322..09ea6a56 100644
--- a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -86,6 +86,8 @@ When your webhook endpoint receives a webhook event, it should respond with a st
The default timeout for each webhook event is 2 seconds. If the webhook endpoint does not respond or responds with a status code other than `200` or `201`, the WaaS service will continue to retry sending the event. If the number of retry attempts reaches 10 , the WaaS service will stop sending the event and the event status will become `Failed`· You can resend the event by clicking **Retry** on **Cobo Portal** > **Developer** > **WaaS 2.0** > **Webhook Events**.
+Webhook events are retained for 7 days after generation. After that window, the event is purged and is no longer retrievable through Cobo Portal or the [List all webhook events](/v2/api-references/developers--webhooks/list-all-webhook-events) / [Retrieve event information](/v2/api-references/developers--webhooks/retrieve-event-information) operations. If you need to backfill missed events, do so before the 7-day window closes, using either the Webhook Event Logs view on **Cobo Portal** > **Developer** > **Webhook Events**, or the [List webhook event logs](/v2/api-references/developers--webhooks/list-webhook-event-logs) and [Retry webhook event by ID](/v2/api-references/developers--webhooks/retry-event) operations.
+
Cobo does not guarantee that events will be delivered in the order they are generated. For example, creating a transfer will generate the following events:
- `wallets.transaction.created`
@@ -188,4 +190,4 @@ async def handle_webhook(
- When receiving the webhook events, your endpoint should first return the correct status code promptly and then handle any subsequent processing asynchronously to prevent timeouts.
- Due to the retry mechanism of webhook events, webhook endpoints may sometimes receive the same event multiple times. To protect against duplicate event processing, please log the event IDs, transaction hashes, or transaction IDs you've already processed and refrain from processing those that are already logged.
-
\ No newline at end of file
+
diff --git a/v2/guides/webhooks-callbacks/subscription-scenarios.mdx b/v2/guides/webhooks-callbacks/subscription-scenarios.mdx
new file mode 100644
index 00000000..e7ba6f0e
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/subscription-scenarios.mdx
@@ -0,0 +1,43 @@
+---
+title: "Webhook subscription scenarios"
+lang: "en"
+description: "Scenario-based guidance for choosing which webhook event types to subscribe to."
+sidebarTitle: "Subscription scenarios"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This guide helps you choose webhook event subscriptions for common transaction workflows.
+
+### Minimal subscription for deposit auto-crediting
+
+Subscribe to `wallets.transaction.succeeded` for deposit auto-crediting. This event is the only Transaction event that indicates a transaction completed successfully. See the crediting rule in [Transaction events](/v2/guides/webhooks-callbacks/webhook-event-type#transaction-events-depositswithdrawalscontract-callsmessage-signing).
+
+If your organization uses KYT or compliance screening, also track `compliance.kyt.screenings.status.updated` and `compliance.disposition.status.updated` when your business logic requires a final disposition before funds are usable. Compliance screening may complete independently of transaction confirmation, so check both event streams when compliance status affects availability.
+
+### Withdrawal status tracking
+
+Use the following event set to track withdrawal status. For the full status and sub-status reference, see [Transaction statuses](/v2/guides/transactions/status).
+
+| Lifecycle signal | Event | How to use it |
+|------------------|-------|---------------|
+| Record created | `wallets.transaction.created` | Store the transaction record. Do not treat this as a final result. |
+| Status or confirmation changed | `wallets.transaction.updated` | Update UI or internal progress state. Do not credit funds from this event. |
+| Terminal success | `wallets.transaction.succeeded` | Mark the withdrawal as completed successfully. |
+| Terminal failure | `wallets.transaction.failed` | Mark the withdrawal as failed and trigger your failure-handling flow. |
+
+### created/updated/succeeded overlap
+
+`wallets.transaction.created`, `wallets.transaction.updated`, and `wallets.transaction.succeeded` are not mutually exclusive stages. `wallets.transaction.updated` fires on every change, including transitions that can also produce `wallets.transaction.created` or `wallets.transaction.succeeded`. If your endpoint subscribes to all three, expect `wallets.transaction.updated` to appear alongside the other events at the same lifecycle points, not as a fourth distinct stage.
+
+### Subscriptions are per-endpoint, channel is org-wide
+
+Each webhook endpoint has its own event-type subscription list, but all endpoints in an organization share one org-wide delivery channel. For example, endpoint A can subscribe only to `wallets.transaction.succeeded`, while endpoint B subscribes to `wallets.transaction.created`, `wallets.transaction.updated`, `wallets.transaction.succeeded`, and `wallets.transaction.failed`. Both endpoints belong to the same organization, and each receives only the event types in its own subscription list.
+
+### Webhook + API reconciliation pattern
+
+Use [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information) as the source of truth for periodic reconciliation against webhook-driven state. This lets you recover from missed deliveries, duplicate deliveries, or processing failures in your own system. For duplicate-delivery handling, see [Important notes](/v2/guides/webhooks-callbacks/set-up-endpoint#important-notes).
+
+Use your Webhook Event Logs to confirm which event patterns apply to transactions initiated outside your API flow, such as Portal-initiated withdrawals or automatic system flows in your organization.
diff --git a/v2/guides/webhooks-callbacks/token-chain-field-dictionary.mdx b/v2/guides/webhooks-callbacks/token-chain-field-dictionary.mdx
new file mode 100644
index 00000000..82368755
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/token-chain-field-dictionary.mdx
@@ -0,0 +1,48 @@
+---
+title: "Token and chain payload field dictionary"
+lang: "en"
+description: "Definitions and trigger behavior for token, chain, and token listing webhook payloads."
+sidebarTitle: "Token and chain field dictionary"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page defines high-signal fields and trigger behavior for token and chain management webhook events.
+
+### Token scope events
+
+`wallet.token.enabled` and `wallet.token.disabled` report an organization-specific change in which tokens are available to use. Cobo emits these events after an update to a token's visibility scope takes effect. A visibility change from public to public emits no event. When a token becomes public, eligible organizations that have not already explicitly enabled it receive `wallet.token.enabled`. When a token stops being public, eligible organizations that are not explicitly retained receive `wallet.token.disabled`. For non-public tokens, organizations added to the access list receive `wallet.token.enabled`, while organizations removed from it receive `wallet.token.disabled`.
+
+Only organizations that are enabled and already have the token's chain enabled for the relevant wallet type receive these events. No single Portal action or API call always precedes them. Automatic token listing approval is one possible cause, but other token visibility updates can also cause these events.
+
+| Field | Description |
+|-------|-------------|
+| `tokens` | The affected token record. Although this field is an array, each event carries exactly one token object describing the token whose availability changed for the wallet scope below: `token_id`, `chain_id`, `asset_id`, `symbol`, `name`, `decimal`, `icon_url`, `token_address`, `fee_token_id`, `can_deposit`, `can_withdraw`, `dust_threshold`, `custodial_minimum_deposit_threshold`, and `asset_model_type`. |
+| `wallet_type` | The wallet family, such as MPC Wallets or Custodial Wallets, whose token availability changed. |
+| `wallet_subtypes` | The affected wallet subtype scope. This field can include more than one value, such as both `Org-Controlled` and `User-Controlled` for MPC Wallets, when the underlying visibility scope maps to multiple subtypes. |
+
+Treat each event as a delta scoped by `wallet_type` and `wallet_subtypes`. For `wallet.token.enabled`, add or refresh the token for those scopes. For `wallet.token.disabled`, stop treating the token as enabled for those scopes. To resynchronize with the current state, call [List enabled tokens](/v2/api-references/wallets/list-enabled-tokens) for your organization and the affected wallet type and subtype.
+
+### Chain scope events
+
+`wallet.chain.enabled` and `wallet.chain.disabled` are emitted by an MFA-guarded organization-facing action. They fire when an organization admin updates which chains their package or wallet type supports.
+
+| Field | Description |
+|-------|-------------|
+| `chains` | The enabled or disabled chain records. Each item follows `ChainInfo`. |
+| `wallet_type` | The wallet family whose chain scope changed. |
+| `wallet_subtypes` | The wallet subtypes affected by the chain-scope change. |
+
+### Token listing events
+
+`wallets.token_listing.succeeded` and `wallets.token_listing.failed` are part of an end-user token listing flow. Organizations create requests with `POST wallets/tokens/listing_requests`. Cobo reviews the request, and the succeeded or failed webhook is emitted when the review reaches a final status.
+
+| Field | Description |
+|-------|-------------|
+| `request_id` | The token listing request identifier. |
+| `status` | Final request status. Values are `Submitted`, `Succeeded`, and `Failed`. |
+| `source` | Request source. Values are `API` and `Admin`. |
+| `feedback` | Review feedback for the request, usually populated when the listing fails. |
+| `token` | The token record produced by a successful listing. It follows `TokenInfo`. |
diff --git a/v2/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx b/v2/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx
new file mode 100644
index 00000000..5cccfc99
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx
@@ -0,0 +1,86 @@
+---
+title: "Token and chain webhook payload examples"
+lang: "en"
+description: "Full JSON examples of token, chain, and token listing webhook event payloads."
+sidebarTitle: "Token and chain payload examples"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page shows complete payload examples for token and chain management webhook events. For the event list, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+
+### Token enabled or disabled
+
+`wallet.token.enabled` and `wallet.token.disabled` deliver a `TokensEventData` payload with `tokens`, `wallet_type`, and `wallet_subtypes`.
+
+```json
+{
+ "tokens": [
+ {
+ "token_id": "ETH_USDT",
+ "name": "Tether USD",
+ "symbol": "USDT",
+ "chain_id": "ETH",
+ "decimal": 6,
+ "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
+ }
+ ],
+ "wallet_type": "MPC",
+ "wallet_subtypes": [
+ "Org-Controlled",
+ "User-Controlled"
+ ]
+}
+```
+
+### Chain enabled or disabled
+
+`wallet.chain.enabled` and `wallet.chain.disabled` deliver a `ChainsEventData` payload with `chains`, `wallet_type`, and `wallet_subtypes`.
+
+```json
+{
+ "chains": [
+ {
+ "chain_id": "ETH",
+ "symbol": "ETH",
+ "icon_url": "https://example.com/chains/eth.png",
+ "explorer_tx_url": "https://etherscan.io/tx/{txn_id}",
+ "explorer_address_url": "https://etherscan.io/address/{address}",
+ "require_memo": false
+ }
+ ],
+ "wallet_type": "MPC",
+ "wallet_subtypes": [
+ "Org-Controlled"
+ ]
+}
+```
+
+### Token listing succeeded or failed
+
+`wallets.token_listing.succeeded` and `wallets.token_listing.failed` deliver a `TokenListing` payload. The payload includes the final request status, request source, optional feedback, and the listed token details.
+
+```json
+{
+ "request_id": "token-listing-20250701-0001",
+ "chain_id": "ETH",
+ "contract_address": "0x1234567890abcdef1234567890abcdef12345678",
+ "wallet_type": "MPC",
+ "wallet_subtype": "Org-Controlled",
+ "token": {
+ "token_id": "ETH_EXAMPLE",
+ "name": "Example Token",
+ "symbol": "EXAMPLE",
+ "chain_id": "ETH",
+ "decimal": 18,
+ "token_address": "0x1234567890abcdef1234567890abcdef12345678"
+ },
+ "status": "Succeeded",
+ "source": "API",
+ "feedback": null,
+ "created_timestamp": 1751328000000,
+ "updated_timestamp": 1751328600000
+}
+```
diff --git a/v2/guides/webhooks-callbacks/transaction-field-dictionary.mdx b/v2/guides/webhooks-callbacks/transaction-field-dictionary.mdx
new file mode 100644
index 00000000..4a31d392
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/transaction-field-dictionary.mdx
@@ -0,0 +1,50 @@
+---
+title: "Transaction payload field dictionary"
+lang: "en"
+description: "Definitions and disambiguation for high-signal fields in the Transaction webhook, callback, and query-API payload."
+sidebarTitle: "Transaction field dictionary"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page defines high-signal `Transaction` fields that often affect webhook, callback, and transaction-query integrations.
+
+### `token_id` vs. `asset_id`
+
+`token_id` is the token or currency identifier for the transaction. It is the field you should use for transaction accounting, deposit crediting, and reconciliation across MPC Wallets, Custodial Wallets, Smart Contract Wallets, and Exchange Wallets. For example, an Ethereum USDT transaction uses `token_id: "ETH_USDT"`.
+
+`asset_id` is populated only when the wallet involved is an Exchange Wallet. For every MPC Wallet, Custodial Wallet, and Smart Contract Wallet transaction, `asset_id` is absent or null.
+
+
+A common integration mistake is treating `asset_id` as a shortened token identifier, such as expecting `asset_id: "USDT"` beside `token_id: "ETH_USDT"`. For MPC Wallets, Custodial Wallets, and Smart Contract Wallets, `asset_id` is always empty. Use `token_id`, not `asset_id`, unless the wallet involved is an Exchange Wallet.
+
+
+### Source and destination direction
+
+For a deposit, `source` shows where funds came from and `destination.wallet_id` is the receiving wallet. For a withdrawal, `source.wallet_id` is the paying wallet and `destination` shows where funds went. For the full type reference, see [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations).
+
+### `request_id`
+
+`request_id` is an optional caller-provided identifier supplied when creating a transaction request. It helps you map the resulting transaction back to a request in your own system. It may be null or absent for transactions that were not created through an API call that supplied `request_id`, such as inbound deposits or requests that omitted it.
+
+### `replacement.replaced_by_transaction_hash`
+
+RBF, or Replace-By-Fee, lets a pending transaction be replaced by another transaction. When a transaction is replaced, `replacement.replaced_by_transaction_hash`, `replacement.replaced_by_transaction_id`, and `replacement.replaced_by_type` on the original transaction point to the transaction that replaced it. The replacing transaction carries `replacement.replaced_transaction_hash`, `replacement.replaced_transaction_id`, and `replacement.replaced_type` to identify the original transaction.
+
+### High-signal `cobo_category` values
+
+`cobo_category` is an array of Cobo-defined category strings that describes the logical category or purpose of a transaction. The Fee-Station-related subset is documented in [Cobo-defined categories](/v2/guides/transactions/manage-transactions#cobo-defined-categories).
+
+Beyond Fee Station, `AutoSweep` is a high-signal value because it identifies an automatic fund-consolidation transaction. It can explain balance movements that were not initiated by an explicit API call. The enum also includes staking, screening, tokenization, and other categories. See [Cobo-defined categories](/v2/guides/transactions/manage-transactions#cobo-defined-categories) for the broader reference.
+
+### `fueling_info` (Fee Station only)
+
+`fueling_info` is populated only when the transaction has an associated Fee Station fueling record; otherwise it is null. Use it with `cobo_category`, especially `AutoFueling`, to connect the Fee Station gas transaction to the fueling request and the main transaction.
+
+| Field | Description |
+|-------|-------------|
+| `request_id` | The Fee Station fueling request identifier. |
+| `transaction_id` | The transaction ID of the gas or fee transaction initiated by Fee Station. |
+| `main_transaction_id` | The transaction ID of the main transaction that required fueling. This field is set only when the current record is a gas or fee transaction initiated by Fee Station. |
diff --git a/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx b/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx
new file mode 100644
index 00000000..0bb2f78a
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx
@@ -0,0 +1,423 @@
+---
+title: "Transaction webhook payload examples"
+lang: "en"
+description: "Full JSON examples of Transaction webhook event payloads for deposits, withdrawals, and different chain and fee models."
+sidebarTitle: "Transaction webhook payload examples"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page shows complete `Transaction` data-type payloads as delivered in `wallets.transaction.*` webhook events. For the event list, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type). For the full `source` and `destination` type reference, see [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations).
+
+### Deposit vs. withdrawal
+
+The following native-coin EVM deposit uses `source.source_type: DepositFromAddress` and `destination.destination_type: DepositToAddress`. The `source` shows where funds came from, and `destination.wallet_id` identifies the receiving wallet.
+
+```json
+{
+ "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
+ "cobo_id": "20250701000101000000000000000000",
+ "request_id": null,
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Deposit",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": [
+ "0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"
+ ]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "1.25"
+ },
+ "result": {
+ "amount": "1.25",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 20,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x9f2c6d8e1a4b3c5d7e901234567890abcdef1234567890abcdef1234567890",
+ "raw_tx_info": {
+ "used_nonce": 9,
+ "raw_tx": "0xa22cb465..."
+ },
+ "replacement": null,
+ "description": null,
+ "created_timestamp": 1751328000000,
+ "updated_timestamp": 1751328060000,
+ "cobo_category": []
+}
+```
+
+An Exchange-Wallet-to-Exchange-Wallet deposit uses `DepositFromWallet` on `source` and `DepositToWallet` on `destination` instead of the address-based deposit types shown above.
+
+The following token withdrawal uses a wallet-origin `source` and an address `destination`. Contract-call and message-sign destinations, such as `EVM_Contract` and `EVM_EIP_191_Signature`, use the same `Transaction` wrapper with different `destination` shapes. See [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) for those destination types.
+
+```json
+{
+ "transaction_id": "b3f2a891-6c4d-4e2a-8f1b-7d5e9c3a2f10",
+ "cobo_id": "20250701000102000000000000000000",
+ "request_id": "withdraw-20250701-0001",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Withdrawal",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "signer_key_share_holder_group_id": "9a0f5d51-3f7d-4d2f-9d7e-a514bf60f2c1"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
+ "amount": "100"
+ }
+ },
+ "result": {
+ "amount": "100",
+ "token_id": "ETH_USDT"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "65000",
+ "gas_used": "61234"
+ },
+ "confirmed_num": 18,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x1d3f5a7c9e0b2d4f6a8c01234567890abcdef1234567890abcdef12345678",
+ "raw_tx_info": {
+ "used_nonce": 10,
+ "raw_tx": "0x02f8b1..."
+ },
+ "replacement": null,
+ "description": "Customer withdrawal",
+ "created_timestamp": 1751328200000,
+ "updated_timestamp": 1751328260000,
+ "cobo_category": []
+}
+```
+
+### Fee models
+
+For EVM transactions using EIP-1559, inspect `raw_tx_info.used_nonce` and `raw_tx_info.raw_tx` when you debug nonce handling or RBF behavior.
+
+```json
+{
+ "transaction_id": "c94d7e12-3a8b-4f6c-9e2d-1f8a5b6c7d34",
+ "cobo_id": "20250701000103000000000000000000",
+ "request_id": "eth-transfer-0001",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "signer_key_share_holder_group_id": "9a0f5d51-3f7d-4d2f-9d7e-a514bf60f2c1"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
+ "amount": "0.5"
+ }
+ },
+ "result": {
+ "amount": "0.5",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 16,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x2b4d6f8a0c1e3f5a7b9d01234567890abcdef1234567890abcdef12345678",
+ "raw_tx_info": {
+ "used_nonce": 9,
+ "raw_tx": "0xa22cb465..."
+ },
+ "replacement": null,
+ "created_timestamp": 1751328300000,
+ "updated_timestamp": 1751328360000,
+ "cobo_category": []
+}
+```
+
+For UTXO transactions, `source.included_utxos` shows requested inputs when they were specified, and `raw_tx_info.selected_utxos` shows the inputs selected for the broadcast transaction.
+
+```json
+{
+ "transaction_id": "d1e8f423-9b6a-4c3d-8e1f-2a7b9c5d6e48",
+ "cobo_id": "20250701000104000000000000000000",
+ "request_id": "btc-transfer-0001",
+ "wallet_id": "6d9f3b29-7841-4b10-85f2-a674dc371ad1",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "BTC",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "6d9f3b29-7841-4b10-85f2-a674dc371ad1",
+ "address": "bc1qsourceaddress000000000000000000000000",
+ "included_utxos": [
+ {
+ "tx_hash": "6f1c9a2b3d4e5f678901234567890abcdef1234567890abcdef1234567890",
+ "vout_n": 0
+ }
+ ]
+ },
+ "destination": {
+ "destination_type": "Address",
+ "utxo_outputs": [
+ {
+ "address": "bc1qdestination000000000000000000000000000",
+ "amount": "0.01"
+ }
+ ]
+ },
+ "result": {
+ "amount": "0.01",
+ "token_id": "BTC"
+ },
+ "fee": {
+ "fee_type": "UTXO",
+ "token_id": "BTC",
+ "fee_used": "0.00015",
+ "fee_rate": "50",
+ "max_fee_amount": "0.0002"
+ },
+ "confirmed_num": 6,
+ "confirming_threshold": 3,
+ "transaction_hash": "4b8e1d6c9f2a34567890abcdef1234567890abcdef1234567890abcdef12",
+ "raw_tx_info": {
+ "selected_utxos": [
+ {
+ "tx_hash": "6f1c9a2b3d4e5f678901234567890abcdef1234567890abcdef1234567890",
+ "vout_n": 0,
+ "token_id": "BTC",
+ "address": "bc1qsourceaddress000000000000000000000000"
+ }
+ ],
+ "utxo_changes": [
+ {
+ "address": "bc1qchangeaddress0000000000000000000000000",
+ "value": "0.00485",
+ "token_id": "BTC"
+ }
+ ]
+ },
+ "replacement": null,
+ "created_timestamp": 1751328400000,
+ "updated_timestamp": 1751328460000,
+ "cobo_category": []
+}
+```
+
+The schema field for UTXO change outputs is `utxo_changes`, a plural array. The singular `utxo_change` field is deprecated and should not be used in new examples or integrations.
+
+TRON-style transactions use the Fixed fee model. The Fixed fee model, used by TRON and similar chains, has no gas or priority-fee sub-fields. It carries `token_id`, `fee_used`, `estimated_fee_used`, and `max_fee_amount`.
+
+```json
+{
+ "transaction_id": "e5a3b678-2c9d-4f1e-8b6a-3d7c8e9f1a52",
+ "cobo_id": "20250701000105000000000000000000",
+ "request_id": "tron-transfer-0001",
+ "wallet_id": "22fb96d7-5d43-4af5-bb8f-c2bb0f57f4a2",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "TRON_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "22fb96d7-5d43-4af5-bb8f-c2bb0f57f4a2",
+ "address": "TSourceAddress111111111111111111111111"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "TDestination1111111111111111111111111",
+ "amount": "50"
+ }
+ },
+ "result": {
+ "amount": "50",
+ "token_id": "TRON_USDT"
+ },
+ "fee": {
+ "fee_type": "Fixed",
+ "token_id": "TRON",
+ "fee_used": "0.1",
+ "estimated_fee_used": "0.1",
+ "max_fee_amount": "0.2"
+ },
+ "confirmed_num": 20,
+ "confirming_threshold": 19,
+ "transaction_hash": "9abf1c2d3e4f567890abcdef1234567890abcdef1234567890abcdef1234",
+ "raw_tx_info": null,
+ "replacement": null,
+ "created_timestamp": 1751328500000,
+ "updated_timestamp": 1751328560000,
+ "cobo_category": []
+}
+```
+
+### Fee Station transactions
+
+`fee_station.transaction.*` events deliver the same `Transaction` payload schema as `wallets.transaction.*` events. The Fee Station variant uses the `fee_station.` event-type prefix and omits wallet-scope metadata fields from `wallet_scopes_info`.
+
+The `type` field does not distinguish Fee Station transactions. Internal Fee Station query types are mapped to the public `Deposit` or `Withdrawal` values before the payload is returned.
+
+The following AutoFueling example uses the same `Transaction` wrapper and adds Fee-Station-specific `cobo_category` and `fueling_info` values.
+
+```json
+{
+ "transaction_id": "f6b7c8d9-0a1b-4c2d-9e3f-456789abcdef",
+ "cobo_id": "20250701000106000000000000000000",
+ "request_id": null,
+ "wallet_id": "fee-station-wallet-001",
+ "type": "Withdrawal",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "fee-station-wallet-001",
+ "address": "0xfee0000000000000000000000000000000000001"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "0.05"
+ }
+ },
+ "result": {
+ "amount": "0.05",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.001",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 15,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x6c7d8e9f01234567890abcdef1234567890abcdef1234567890abcdef1234",
+ "raw_tx_info": {
+ "used_nonce": 11,
+ "raw_tx": "0x02f901..."
+ },
+ "replacement": null,
+ "description": "AutoFueling transaction",
+ "created_timestamp": 1751328600000,
+ "updated_timestamp": 1751328660000,
+ "cobo_category": ["AutoFueling"],
+ "fueling_info": {
+ "request_id": "fuel-20250701-0001",
+ "transaction_id": "f6b7c8d9-0a1b-4c2d-9e3f-456789abcdef",
+ "main_transaction_id": "b3f2a891-6c4d-4e2a-8f1b-7d5e9c3a2f10"
+ }
+}
+```
+
+Use `cobo_category` to identify Fee-Station-specific transaction categories. These values are documented in [Cobo-defined categories](/v2/guides/transactions/manage-transactions#cobo-defined-categories).
+
+### Native coin vs. token, and Exchange Wallet asset_id
+
+For MPC Wallet, Custodial Wallet, and Smart Contract Wallet transactions, use `token_id` to identify the currency or token. `asset_id` is absent or null even for token transactions.
+
+```json
+[
+ {
+ "type": "Deposit",
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": ["0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "1.25"
+ }
+ },
+ {
+ "type": "Deposit",
+ "token_id": "ETH_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": ["0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "100"
+ }
+ },
+ {
+ "type": "Withdrawal",
+ "token_id": "TRON_USDT",
+ "asset_id": "USDT",
+ "source": {
+ "source_type": "Main",
+ "exchange_id": "binance-main"
+ },
+ "destination": {
+ "destination_type": "ExchangeWallet",
+ "exchange_id": "okx-main"
+ }
+ }
+]
+```
+
+This array is trimmed to the fields relevant to the `token_id` and `asset_id` contrast and is not a complete `Transaction` payload. A full `Transaction` payload includes the complete `source` and `destination` objects, as shown in the full examples above.
+
+`asset_id` is populated only when the wallet involved is an Exchange Wallet. For every other wallet type, it is absent or null. For details, see [`token_id` vs. `asset_id`](/v2/guides/webhooks-callbacks/transaction-field-dictionary#token_id-vs-asset_id).
diff --git a/v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx b/v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx
new file mode 100644
index 00000000..58a1ebc6
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx
@@ -0,0 +1,44 @@
+---
+title: "TSS request payload field dictionary"
+lang: "en"
+description: "Definitions and trigger behavior for fields in the TSSRequest webhook payload."
+sidebarTitle: "TSS request field dictionary"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page defines high-signal `TSSRequest` fields used by `wallets.mpc.tss_request.*` webhook events. The webhook payload matches the documented `TSSRequest` schema exactly, with no extra or omitted fields.
+
+### Request type
+
+| Value | Description |
+|-------|-------------|
+| `KeyGen` | Creates a new key share holder group. |
+| `KeyGenFromKeyGroup` | Creates a new key share holder group from an existing key group. |
+| `Recovery` | Recovers or reshapes an existing key share holder group. |
+
+These values are defined by the `TSSRequest` schema.
+
+### Request status
+
+| Value | Description |
+|-------|-------------|
+| `PendingKeyHolderConfirmation` | The request is waiting for enough key share holders to approve. |
+| `KeyHolderConfirmationFailed` | Key share holders failed to approve the action to be done to the TSS request. |
+| `KeyGenerating` | The key share is currently being generated for the action to be done to the TSS request. |
+| `MPCProcessing` | The TSS request approval is waiting to be started or is in progress. |
+| `KeyGeneratingFailed` | The key share generation process has failed for the action to be done to the TSS request. |
+| `Success` | The request completed successfully. |
+
+These values are defined by the `TSSRequest` schema.
+
+### Event trigger behavior
+
+| Event type | Trigger |
+|------------|---------|
+| `wallets.mpc.tss_request.created` | The request is newly created or enters the new-request status. |
+| `wallets.mpc.tss_request.succeeded` | The request status becomes `Success`. |
+| `wallets.mpc.tss_request.failed` | The request reaches a final failed status. |
+| `wallets.mpc.tss_request.updated` | Any other supported status transition. This fallback is restricted to portal key generation and reshare requests. |
diff --git a/v2/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx b/v2/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx
new file mode 100644
index 00000000..e3f9a7a5
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx
@@ -0,0 +1,50 @@
+---
+title: "TSS request webhook payload examples"
+lang: "en"
+description: "Full JSON examples of TSSRequest webhook event payloads for MPC key generation and recovery requests."
+sidebarTitle: "TSS request webhook payload examples"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page shows complete `TSSRequest` data-type payloads as delivered in `wallets.mpc.tss_request.*` webhook events. For the event list, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+
+### KeyGen request created
+
+A `KeyGen` request can carry `source_key_share_holder_group: null`. This field is empty for `KeyGen` requests and populated for reshare or migrate-style requests.
+
+```json
+{
+ "tss_request_id": "tss-req-20250701-0001",
+ "source_key_share_holder_group": null,
+ "target_key_share_holder_group_id": "kshg-target-001",
+ "type": "KeyGen",
+ "status": "PendingKeyHolderConfirmation",
+ "description": "Create an MPC key share holder group",
+ "created_timestamp": 1751328000000
+}
+```
+
+### Recovery request succeeded
+
+For a `Recovery` request, `source_key_share_holder_group` identifies the source key share holder group and the TSS Node IDs included in that source group.
+
+```json
+{
+ "tss_request_id": "tss-req-20250701-0002",
+ "source_key_share_holder_group": {
+ "key_share_holder_group_id": "kshg-source-001",
+ "tss_node_ids": [
+ "tss-node-001",
+ "tss-node-002"
+ ]
+ },
+ "target_key_share_holder_group_id": "kshg-target-002",
+ "type": "Recovery",
+ "status": "Success",
+ "description": "Recover an MPC key share holder group",
+ "created_timestamp": 1751328600000
+}
+```
diff --git a/v2/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx b/v2/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx
new file mode 100644
index 00000000..ee2f56d9
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx
@@ -0,0 +1,34 @@
+---
+title: "Wallet and address payload field dictionary"
+lang: "en"
+description: "Definitions and integration notes for wallet, address, and MPC vault webhook payload fields."
+sidebarTitle: "Wallet and address field dictionary"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page defines high-signal fields used by wallet and address management webhook events.
+
+### `addresses`
+
+`addresses` is an array of created wallet addresses. A single-address creation event still uses the same array wrapper. Each item contains `wallet_id` plus the `AddressInfo` fields `address`, `chain_id`, `memo`, `path`, `encoding`, `pubkey`, `x_only_pubkey`, `root_pubkey`, `taproot_script_tree_hash`, `taproot_internal_address`, and `stellar_trusted_token_ids`.
+
+For Solana Associated Token Account activation, see the note in [Wallet and address management events](/v2/guides/webhooks-callbacks/webhook-event-type#wallet-and-address-management-events).
+
+### `WalletInfo`
+
+`WalletInfo` is a oneOf payload selected by wallet type. The dispatch path is shared across wallet types, including MPC vault-wallet and Custodial wallet creation.
+
+| Field | Description |
+|-------|-------------|
+| `wallet_id` | The created wallet identifier. |
+| `wallet_type` | The wallet family, such as `MPC`, that determines which oneOf branch is returned. |
+| `wallet_subtype` | The subtype inside the wallet family, such as `Org-Controlled`. |
+| `vault_id` | For an `MPCWalletInfo` payload, the MPC vault that owns the wallet. |
+| `project_id` | For an `MPCWalletInfo` payload, the project associated with the wallet. |
+
+### `MPCVault`
+
+`MPCVault` identifies the created vault and the root public keys generated for it. `root_pubkeys` is an array of `RootPubkey` objects with `root_pubkey` and `curve`, not an array of strings.
diff --git a/v2/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx b/v2/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx
new file mode 100644
index 00000000..8f9f5d42
--- /dev/null
+++ b/v2/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx
@@ -0,0 +1,90 @@
+---
+title: "Wallet and address webhook payload examples"
+lang: "en"
+description: "Full JSON examples of wallet, address, and MPC vault management webhook event payloads."
+sidebarTitle: "Wallet and address payload examples"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+
+
+This page shows complete payload examples for wallet and address management webhook events. For the event list, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+
+### Address creation
+
+`wallets.addresses.created` delivers an `Addresses` payload. It fires for both single and batch address creation, and the `addresses` array carries every address created in that batch.
+
+```json
+{
+ "addresses": [
+ {
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "chain_id": "ETH",
+ "memo": null,
+ "path": "m/44'/60'/0'/0/0",
+ "encoding": null,
+ "pubkey": "03f0288924f1c...",
+ "x_only_pubkey": null,
+ "root_pubkey": "xpub6CUGRU...",
+ "taproot_script_tree_hash": null,
+ "taproot_internal_address": null,
+ "stellar_trusted_token_ids": []
+ },
+ {
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "bc1qexampleaddress0000000000000000000000000",
+ "chain_id": "BTC",
+ "memo": null,
+ "path": "m/84'/0'/0'/0/0",
+ "encoding": "ENCODING_BECH32",
+ "pubkey": "02c6047f9441ed...",
+ "x_only_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
+ "root_pubkey": "xpub6DExample...",
+ "taproot_script_tree_hash": null,
+ "taproot_internal_address": "bc1pinternaladdress000000000000000000000000",
+ "stellar_trusted_token_ids": []
+ }
+ ]
+}
+```
+
+### Wallet creation
+
+`wallets.created` delivers a `WalletInfo` payload. The webhook is emitted from a shared wallet-creation path used across wallet types, and the payload variant matches the wallet type.
+
+```json
+{
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "wallet_subtype": "Org-Controlled",
+ "name": "Treasury MPC Wallet",
+ "vault_id": "vault-20250701-001",
+ "project_id": "project-20250701-001"
+}
+```
+
+### MPC vault creation
+
+`mpc_vaults.created` delivers an `MPCVault` payload. It fires for both Org-Controlled and User-Controlled vaults, and `root_pubkeys` is a list of objects rather than a list of bare strings.
+
+```json
+{
+ "vault_id": "vault-20250701-001",
+ "project_id": "project-20250701-001",
+ "name": "Treasury MPC Vault",
+ "type": "Org-Controlled",
+ "root_pubkeys": [
+ {
+ "root_pubkey": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...",
+ "curve": "SECP256K1"
+ },
+ {
+ "root_pubkey": "xpub6DExampleRootPubkeyForEd25519...",
+ "curve": "ED25519"
+ }
+ ],
+ "created_timestamp": 1751328000000
+}
+```
diff --git a/v2/guides/webhooks-callbacks/webhook-event-type.mdx b/v2/guides/webhooks-callbacks/webhook-event-type.mdx
index 0acafca6..9f35fd0c 100644
--- a/v2/guides/webhooks-callbacks/webhook-event-type.mdx
+++ b/v2/guides/webhooks-callbacks/webhook-event-type.mdx
@@ -63,6 +63,16 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+For complete example payloads of the `Transaction` data type, see [Transaction webhook payload examples](/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples).
+
+Only the `wallets.transaction.succeeded` event indicates that a transaction has completed successfully. This is the only Transaction event safe to trigger deposit fund-crediting from. `wallets.transaction.updated` fires on every status change during a transaction's entire lifecycle, including states before the transaction is confirmed or even broadcast, so it must never be used to credit funds. Use it only for status or UI tracking. The same applies to Confirming-stage notifications: they indicate progress, not completion. Wait for `wallets.transaction.succeeded` or poll [Get transaction information](/v2/api-references/transactions/get-transaction-information) for `status: Success` before crediting a deposit.
+
+### Callback-stage transaction payloads
+
+When a callback message is sent, its `Transaction` payload uses the same schema as the webhook event and query-API payloads. For the difference between webhooks and callbacks, see [Webhooks vs callbacks](/v2/guides/webhooks-callbacks/introduction#webhooks-vs-callbacks).
+
+Because a callback is triggered when you initiate a withdrawal or contract call, before the transaction is broadcast to the chain or confirmed, several fields on that payload will not yet be populated. The fields most commonly seen unpopulated at callback time include `cobo_id`, `asset_id`, `result`, `confirmed_num`, and `confirming_threshold`, because the values they represent, such as the chain broadcast tracking ID, exchange asset accounting, execution result, and confirmation counts, do not exist until the transaction has been broadcast and started confirming. `cobo_category` may also be empty at this stage. These are common examples; the schema's nullable fields in general may be empty depending on the transaction stage.
+
### Fee Station events
@@ -97,6 +107,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+For complete example payloads of the Fee Station `Transaction` data type, see [Fee Station transactions](/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples#fee-station-transactions).
+
### MPC TSS request events
@@ -131,6 +143,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+For complete example payloads of the `TSSRequest` data type, see [TSS request webhook payload examples](/v2/guides/webhooks-callbacks/tss-request-webhook-payload-examples).
+
### Wallet and address management events
@@ -162,6 +176,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
Activating a Solana token sub-address (Associated Token Account) does not emit a `wallets.addresses.created` event. The rent transfer that funds the activation does not emit any `wallets.transaction.*` event and does not produce a deposit or transaction record. As a result, Solana token account activation and its rent are not visible through webhooks. For details, see [Solana token account rent](/v2/guides/transactions/solana-token-account-rent).
+For complete example payloads of the `Addresses`, `WalletInfo`, and `MPCVault` data types, see [Wallet and address webhook payload examples](/v2/guides/webhooks-callbacks/wallet-address-webhook-payload-examples).
+
### Token and chain management events
@@ -206,6 +222,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+For complete example payloads of the `Tokens`, `Chains`, and `TokenListing` data types, see [Token and chain webhook payload examples](/v2/guides/webhooks-callbacks/token-chain-webhook-payload-examples).
+
### Balance update events
@@ -230,6 +248,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+For complete example payloads of the `BalanceUpdateInfo` data type, see [Balance update webhook payload examples](/v2/guides/webhooks-callbacks/balance-update-webhook-payload-examples).
+
### Compliance events
@@ -254,6 +274,42 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+### `ComplianceDisposition` event data
+
+The `compliance.disposition.status.updated` event notifies you that the status of a compliance disposition has changed for a transaction. The `ComplianceDisposition` payload includes `transaction_id`, `disposition_type`, `disposition_status`, `destination_address`, `disposition_amount`, and `updated_timestamp`.
+
+Cobo emits this event when your organization's Screening App integration reports a disposition status change. Because the update originates from the Screening App, treat it as that service's current view of the disposition rather than a status Cobo computed locally. Use `transaction_id` to correlate the event with the transaction you called [Refund funds](/v2/api-references/compliance/refund-funds), [Isolate funds](/v2/api-references/compliance/isolate-funds), or [Unfreeze frozen funds](/v2/api-references/compliance/unfreeze-frozen-funds) on.
+
+**`disposition_type` (`DispositionType`)**
+
+| Value | Meaning |
+|-------|---------|
+| `Refund` | The disposition was created by calling [Refund funds](/v2/api-references/compliance/refund-funds). |
+| `Isolate` | The disposition was created by calling [Isolate funds](/v2/api-references/compliance/isolate-funds). |
+| `Unfreeze` | The disposition was created by calling [Unfreeze frozen funds](/v2/api-references/compliance/unfreeze-frozen-funds). |
+
+Each operation submits the disposition request to your organization's Screening App integration for processing.
+
+**`disposition_status` (`DispositionStatus`)**
+
+| Value | Meaning |
+|-------|---------|
+| `Submitted` | The disposition request has been submitted. |
+| `Refunding` | A refund of the funds is in progress. |
+| `Refunded` | The funds have been refunded. |
+| `RefundFailed` | The refund attempt failed. |
+| `Frozen` | The associated funds have been frozen. |
+| `Unfreezing` | The funds are being unfrozen. |
+| `Unfrozen` | The funds have been unfrozen. |
+| `UnfreezeFailed` | The attempt to unfreeze the funds failed. |
+| `Isolating` | The funds are being isolated. |
+| `Isolated` | The funds have been isolated. |
+| `IsolateFailed` | The attempt to isolate the funds failed. |
+| `CoboDisposition` | The funds are being handled through a Cobo disposition. |
+| `Normal` | The funds are in a normal state with no compliance action applied. |
+
+When you receive this event, record the reported `disposition_type` and `disposition_status` as an update to that transaction's disposition state, keyed by `transaction_id`. To confirm the current disposition state at any time, such as before deciding on further action, call [Get disposition status](/v2/api-references/compliance/get-disposition-status) for that transaction.
+
### `ComplianceKytScreenings` event data
The `compliance.kyt.screenings.status.updated` event carries a `ComplianceKytScreenings` payload (`KytScreeningsEventData`). This payload reports two independent status fields, `review_status` and `funds_status`. Track them separately: `review_status` reflects the screening and review progress of the case, and `funds_status` reflects the state of the associated funds.
@@ -293,8 +349,10 @@ The case decision that drives these status changes is represented by `KytScreeni
## Data structure of webhook events
For a complete introduction of the webhook event data and its data structure, refer to the [data](/v2/api-references/developers--webhooks/retrieve-event-information#response-data) property in the response of the Retrieve event information operation or the [data.data](/v2/api-references/developers--webhooks/list-all-webhook-events#response-data-data) property in the response of the List all webhook event operation.
+For full worked JSON examples of the `Transaction` data type across deposits, withdrawals, and different chains, see [Transaction webhook payload examples](/v2/guides/webhooks-callbacks/transaction-webhook-payload-examples).
+
Switch between the event data types to view the data structure of each event data type.
-Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**.
\ No newline at end of file
+Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**.
diff --git a/v2_cn/guides/webhooks-callbacks/balance-update-field-dictionary.mdx b/v2_cn/guides/webhooks-callbacks/balance-update-field-dictionary.mdx
new file mode 100644
index 00000000..9bda0390
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/balance-update-field-dictionary.mdx
@@ -0,0 +1,32 @@
+---
+title: "Balance update 负载字段词典"
+lang: "zh-hans"
+description: "定义 BalanceUpdateInfo Webhook 负载字段及触发行为。"
+sidebarTitle: "Balance update 字段词典"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文定义 `BalanceUpdateInfo` Webhook 事件的高频字段和触发行为。
+
+### Trigger behavior
+
+两种 balance update 事件类型使用相同的负载结构。触发的事件类型 —— `wallet.mpc.balance.updated` 或 `wallet.web3.balance.updated` —— 取决于引发该 balance 变化的 wallet type。
+
+当 Cobo 的 chain-scanning 和 balance-refresh pipeline 检测到新的或已变化的链上余额时，该事件会触发。它不是固定周期的 reconciliation job，也不依赖 transaction ledger completion。
+
+### Field dictionary
+
+| 字段 | 说明 |
+|-------|-------------|
+| `token_id` | 余额发生变化的 token 或 currency。 |
+| `address` | 被刷新余额的 on-chain address。 |
+| `wallet_uuid` | 此 balance 负载中的 wallet identifier。该字段名为 `wallet_uuid`，不是 Transaction 和 Addresses 负载中常见的 `wallet_id`。 |
+| `updated_timestamp` | 记录 balance update 的时间。 |
+| `balance.total` | 该 address 上该 token 的 total balance。`Balance` schema 要求此字段。 |
+| `balance.available` | 当前可用的 balance。`Balance` schema 要求此字段。 |
+| `balance.pending` | 等待最终可用的 balance。 |
+| `balance.locked` | 由于平台或流程约束而 locked 的 balance。 |
+| `balance.frozen` | 由于 compliance 或 risk control 而 frozen 的 balance。 |
diff --git a/v2_cn/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx b/v2_cn/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx
new file mode 100644
index 00000000..202b95c5
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/balance-update-webhook-payload-examples.mdx
@@ -0,0 +1,30 @@
+---
+title: "Balance update Webhook 负载示例"
+lang: "zh-hans"
+description: "展示 BalanceUpdateInfo Webhook 事件负载的完整 JSON 示例。"
+sidebarTitle: "Balance update 负载示例"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文展示 `wallet.mpc.balance.updated` 和 `wallet.web3.balance.updated` Webhook 事件中传递的完整 `BalanceUpdateInfo` 负载。事件列表请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。
+
+`wallet.mpc.balance.updated` 和 `wallet.web3.balance.updated` 使用相同的 schema，只是触发事件的钱包类型不同。
+
+```json
+{
+ "token_id": "ETH_USDT",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "updated_timestamp": 1751328600000,
+ "balance": {
+ "total": "1250.50",
+ "available": "1200.00",
+ "pending": "25.50",
+ "locked": "20.00",
+ "frozen": "5.00"
+ }
+}
+```
diff --git a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
index ae7e44c0..f779f06f 100644
--- a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -86,6 +86,8 @@ Ed25519 签名是基于 HTTP 请求包体的原始字节精确计算的。您必
默认情况下，每个 Webhook 事件的超时时间为 2 秒。如果 Webhook Endpoint 没有响应或响应状态码不是 `200` 或 `201`，WaaS 服务将继续重试发送事件。如果重试次数达到 10 次，WaaS 服务将停止发送事件，事件状态将变为**发送失败**。您可以通过单击 Cobo Portal > 开发者 > WaaS 2.0 > Webhook 事件上的**重新发送**来重新发送事件。
+Webhook 事件在生成后保留 7 天。超过该窗口后，事件会被清除，并且无法再通过 Cobo Portal 或 [List all webhook events](/v2/api-references/developers--webhooks/list-all-webhook-events) / [Retrieve event information](/v2/api-references/developers--webhooks/retrieve-event-information) 操作检索。如果您需要回填漏收事件，请在 7 天窗口结束前完成，可使用 **Cobo Portal** > **开发者** > **Webhook 事件** 中的 Webhook Event Logs 视图，或使用 [List webhook event logs](/v2/api-references/developers--webhooks/list-webhook-event-logs) 和 [Retry webhook event by ID](/v2/api-references/developers--webhooks/retry-event) 操作。
+
Cobo 不保证事件将按生成顺序交付。例如，创建转账将生成以下事件：
- `wallets.transaction.created`
@@ -175,4 +177,4 @@ async def handle_webhook(
- 在接收 Webhook 事件时，您的 Endpoint 应该首先快速返回正确的状态码，然后异步处理任何后续处理，以防止超时。
- 由于 Webhook 事件存在重试机制，Webhook Endpoint 有时会多次接收到相同的事件。为了防止重复事件处理，请记录已处理的 Event ID，Transaction Hash 或 Transaction ID，并避免处理已记录的事件。
-
\ No newline at end of file
+
diff --git a/v2_cn/guides/webhooks-callbacks/subscription-scenarios.mdx b/v2_cn/guides/webhooks-callbacks/subscription-scenarios.mdx
new file mode 100644
index 00000000..1c46d620
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/subscription-scenarios.mdx
@@ -0,0 +1,43 @@
+---
+title: "Webhook 订阅场景"
+lang: "zh-hans"
+description: "基于场景说明如何选择要订阅的 Webhook 事件类型。"
+sidebarTitle: "订阅场景"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文帮助您为常见交易工作流选择 Webhook 事件订阅。
+
+### 充币自动入账的最小订阅
+
+订阅 `wallets.transaction.succeeded` 即可用于充币自动入账。此事件是唯一表示交易已成功完成的 Transaction 事件。请参阅 [Transaction events](/v2_cn/guides/webhooks-callbacks/webhook-event-type#transaction-events-depositswithdrawalscontract-callsmessage-signing) 中的入账规则。
+
+如果您的组织使用 KYT 或合规扫描，并且您的业务逻辑要求资金可用前必须有最终处置结果，请同时跟踪 `compliance.kyt.screenings.status.updated` 和 `compliance.disposition.status.updated`。合规扫描可能独立于交易确认完成，因此当合规状态影响资金可用性时，请同时检查这两类事件流。
+
+### 提币状态跟踪
+
+使用以下事件集合跟踪提币状态。完整的 status 和 sub-status 参考请参阅 [Transaction statuses](/v2_cn/guides/transactions/status)。
+
+| 生命周期信号 | 事件 | 使用方式 |
+|-------------|------|---------|
+| 记录已创建 | `wallets.transaction.created` | 存储交易记录。不要将此事件视为最终结果。 |
+| status 或确认数发生变化 | `wallets.transaction.updated` | 更新 UI 或内部进度状态。不要基于此事件入账。 |
+| 终态成功 | `wallets.transaction.succeeded` | 将提币标记为成功完成。 |
+| 终态失败 | `wallets.transaction.failed` | 将提币标记为失败，并触发您的失败处理流程。 |
+
+### created/updated/succeeded 重叠
+
+`wallets.transaction.created`、`wallets.transaction.updated` 和 `wallets.transaction.succeeded` 不是互斥阶段。`wallets.transaction.updated` 会在每次变化时触发，包括也可能产生 `wallets.transaction.created` 或 `wallets.transaction.succeeded` 的转换点。如果您的 Endpoint 同时订阅这三个事件，应预期 `wallets.transaction.updated` 会在相同生命周期点与其他事件同时出现，而不是作为第四个独立阶段。
+
+### 订阅按 Endpoint 配置，channel 按组织共享
+
+每个 Webhook Endpoint 都有自己的事件类型订阅列表，但同一组织中的所有 Endpoint 共享一个组织级投递 channel。例如，Endpoint A 可以只订阅 `wallets.transaction.succeeded`，而 Endpoint B 订阅 `wallets.transaction.created`、`wallets.transaction.updated`、`wallets.transaction.succeeded` 和 `wallets.transaction.failed`。两个 Endpoint 都属于同一组织，并且各自只接收自己订阅列表中的事件类型。
+
+### Webhook + API 对账模式
+
+请使用 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 作为定期对账 Webhook 驱动状态的事实来源。这可帮助您从漏投、重复投递或您系统中的处理失败中恢复。重复投递处理请参阅 [Important notes](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#important-notes)。
+
+请使用您自己的 Webhook Event Logs 确认 API 流程之外发起的交易适用哪些事件模式，例如通过 Portal 发起的提币或组织中的自动系统流程。
diff --git a/v2_cn/guides/webhooks-callbacks/token-chain-field-dictionary.mdx b/v2_cn/guides/webhooks-callbacks/token-chain-field-dictionary.mdx
new file mode 100644
index 00000000..8ed5e604
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/token-chain-field-dictionary.mdx
@@ -0,0 +1,48 @@
+---
+title: "Token 和 chain 负载字段词典"
+lang: "zh-hans"
+description: "定义 token、chain 和 token listing Webhook 负载字段及触发行为。"
+sidebarTitle: "Token 和 chain 字段词典"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文定义 token 和 chain management Webhook 事件的高频字段及触发行为。
+
+### Token scope events
+
+`wallet.token.enabled` 和 `wallet.token.disabled` 表示机构可用 token 范围发生了变化。Token 的可见范围更新生效后，Cobo 会发出这些事件。如果 token 在更新前后均为公开状态，则不会发出事件。当 token 变为公开状态时，尚未显式启用该 token 的符合条件机构会收到 `wallet.token.enabled`。当 token 不再为公开状态时，未显式保留该 token 的符合条件机构会收到 `wallet.token.disabled`。对于非公开 token，新增至访问列表的机构会收到 `wallet.token.enabled`，从访问列表移除的机构会收到 `wallet.token.disabled`。
+
+只有已启用，并且已为相关 wallet type 启用该 token 所属 chain 的机构才会收到这些事件。事件发生前并不一定存在某个特定的 Portal 操作或 API 调用。Token 自动上币审批是可能的触发原因之一，其他 token 可见范围更新也可能触发这些事件。
+
+| 字段 | 说明 |
+|-------|-------------|
+| `tokens` | 受影响的 token 记录。虽然该字段是数组，但每个事件仅包含一个 token 对象，用于描述在下述钱包范围内可用性发生变化的 token：`token_id`、`chain_id`、`asset_id`、`symbol`、`name`、`decimal`、`icon_url`、`token_address`、`fee_token_id`、`can_deposit`、`can_withdraw`、`dust_threshold`、`custodial_minimum_deposit_threshold` 和 `asset_model_type`。 |
+| `wallet_type` | Token 可用性发生变化的钱包类别，例如 MPC 钱包或托管钱包。 |
+| `wallet_subtypes` | 受影响的 wallet subtype 范围。当底层可见范围映射到多个 subtype 时，该字段可以包含多个值，例如 MPC 钱包的 `Org-Controlled` 和 `User-Controlled`。 |
+
+将每个事件视为以 `wallet_type` 和 `wallet_subtypes` 为范围的增量更新。对于 `wallet.token.enabled`，请在这些范围内添加或刷新该 token。对于 `wallet.token.disabled`，请停止在这些范围内将该 token 视为已启用。要与当前状态重新同步，请针对你的机构以及受影响的 wallet type 和 subtype 调用 [List enabled tokens](/v2/api-references/wallets/list-enabled-tokens)。
+
+### Chain scope events
+
+`wallet.chain.enabled` 和 `wallet.chain.disabled` 由需要 MFA 的 organization-facing action 发出。当 organization admin 更新其 package 或 wallet type 支持的 chain 时，这些事件会触发。
+
+| 字段 | 说明 |
+|-------|-------------|
+| `chains` | 已 enabled 或 disabled 的 chain record。每个条目遵循 `ChainInfo`。 |
+| `wallet_type` | chain scope 发生变化的 wallet family。 |
+| `wallet_subtypes` | chain-scope change 影响的 wallet subtype。 |
+
+### Token listing events
+
+`wallets.token_listing.succeeded` 和 `wallets.token_listing.failed` 属于 end-user token listing flow。Organization 通过 `POST wallets/tokens/listing_requests` 创建请求。Cobo 会审核该请求，并在审核得出最终状态时发出 succeeded 或 failed webhook。
+
+| 字段 | 说明 |
+|-------|-------------|
+| `request_id` | token listing request 标识符。 |
+| `status` | 最终 request status。取值为 `Submitted`、`Succeeded` 和 `Failed`。 |
+| `source` | request source。取值为 `API` 和 `Admin`。 |
+| `feedback` | 请求的 review feedback，通常在 listing 失败时填充。 |
+| `token` | listing 成功后生成的 token record。它遵循 `TokenInfo`。 |
diff --git a/v2_cn/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx b/v2_cn/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx
new file mode 100644
index 00000000..45c782db
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/token-chain-webhook-payload-examples.mdx
@@ -0,0 +1,86 @@
+---
+title: "Token 和 chain Webhook 负载示例"
+lang: "zh-hans"
+description: "展示 token、chain 和 token listing Webhook 事件负载的完整 JSON 示例。"
+sidebarTitle: "Token 和 chain 负载示例"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文展示 token 和 chain management Webhook 事件的完整负载示例。事件列表请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。
+
+### Token enabled or disabled
+
+`wallet.token.enabled` 和 `wallet.token.disabled` 传递 `TokensEventData` 负载，其中包含 `tokens`、`wallet_type` 和 `wallet_subtypes`。
+
+```json
+{
+ "tokens": [
+ {
+ "token_id": "ETH_USDT",
+ "name": "Tether USD",
+ "symbol": "USDT",
+ "chain_id": "ETH",
+ "decimal": 6,
+ "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
+ }
+ ],
+ "wallet_type": "MPC",
+ "wallet_subtypes": [
+ "Org-Controlled",
+ "User-Controlled"
+ ]
+}
+```
+
+### Chain enabled or disabled
+
+`wallet.chain.enabled` 和 `wallet.chain.disabled` 传递 `ChainsEventData` 负载，其中包含 `chains`、`wallet_type` 和 `wallet_subtypes`。
+
+```json
+{
+ "chains": [
+ {
+ "chain_id": "ETH",
+ "symbol": "ETH",
+ "icon_url": "https://example.com/chains/eth.png",
+ "explorer_tx_url": "https://etherscan.io/tx/{txn_id}",
+ "explorer_address_url": "https://etherscan.io/address/{address}",
+ "require_memo": false
+ }
+ ],
+ "wallet_type": "MPC",
+ "wallet_subtypes": [
+ "Org-Controlled"
+ ]
+}
+```
+
+### Token listing succeeded or failed
+
+`wallets.token_listing.succeeded` 和 `wallets.token_listing.failed` 传递 `TokenListing` 负载。该负载包含最终 request status、request source、可选 feedback 和 listed token 详情。
+
+```json
+{
+ "request_id": "token-listing-20250701-0001",
+ "chain_id": "ETH",
+ "contract_address": "0x1234567890abcdef1234567890abcdef12345678",
+ "wallet_type": "MPC",
+ "wallet_subtype": "Org-Controlled",
+ "token": {
+ "token_id": "ETH_EXAMPLE",
+ "name": "Example Token",
+ "symbol": "EXAMPLE",
+ "chain_id": "ETH",
+ "decimal": 18,
+ "token_address": "0x1234567890abcdef1234567890abcdef12345678"
+ },
+ "status": "Succeeded",
+ "source": "API",
+ "feedback": null,
+ "created_timestamp": 1751328000000,
+ "updated_timestamp": 1751328600000
+}
+```
diff --git a/v2_cn/guides/webhooks-callbacks/transaction-field-dictionary.mdx b/v2_cn/guides/webhooks-callbacks/transaction-field-dictionary.mdx
new file mode 100644
index 00000000..ba1c5e7c
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/transaction-field-dictionary.mdx
@@ -0,0 +1,50 @@
+---
+title: "Transaction 负载字段词典"
+lang: "zh-hans"
+description: "定义并区分 Transaction Webhook、Callback 和查询 API 负载中的高频关键字段。"
+sidebarTitle: "Transaction 字段词典"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文定义会影响 Webhook、Callback 和交易查询集成的高频 `Transaction` 字段。
+
+### `token_id` vs. `asset_id`
+
+`token_id` 是交易的代币或币种标识符。您应该在 MPC Wallet、Custodial Wallet、Smart Contract Wallet 和 Exchange Wallet 的交易记账、充币入账和对账逻辑中使用此字段。例如，Ethereum USDT 交易使用 `token_id: "ETH_USDT"`。
+
+只有当涉及的钱包是 Exchange Wallet 时，`asset_id` 才会被填充。对于每一笔 MPC Wallet、Custodial Wallet 和 Smart Contract Wallet 交易，`asset_id` 都不存在或为 null。
+
+
+一种常见的集成错误是把 `asset_id` 当成缩短版代币标识符，例如在 `token_id: "ETH_USDT"` 旁边期待出现 `asset_id: "USDT"`。对于 MPC Wallet、Custodial Wallet 和 Smart Contract Wallet，`asset_id` 始终为空。除非涉及的钱包是 Exchange Wallet，否则请使用 `token_id`，不要使用 `asset_id`。
+
+
+### Source 和 destination 方向
+
+对于充币，`source` 表示资金来自哪里，`destination.wallet_id` 是接收钱包。对于提币，`source.wallet_id` 是付款钱包，`destination` 表示资金去向。完整类型参考请参阅 [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations)。
+
+### `request_id`
+
+`request_id` 是创建交易请求时由调用方提供的可选标识符。它可帮助您将生成的交易映射回您系统中的请求。对于未通过提供了 `request_id` 的 API 调用创建的交易，例如入站充币或省略该字段的请求，`request_id` 可能为 null 或不存在。
+
+### `replacement.replaced_by_transaction_hash`
+
+RBF（Replace-By-Fee）允许用另一笔交易替换待处理交易。当一笔交易被替换时，原交易上的 `replacement.replaced_by_transaction_hash`、`replacement.replaced_by_transaction_id` 和 `replacement.replaced_by_type` 指向替换它的交易。替换交易会携带 `replacement.replaced_transaction_hash`、`replacement.replaced_transaction_id` 和 `replacement.replaced_type` 来标识原交易。
+
+### 高频 `cobo_category` 值
+
+`cobo_category` 是 Cobo 定义的类别字符串数组，用于描述交易的逻辑类别或用途。Fee Station 相关子集已在 [Cobo-defined categories](/v2_cn/guides/transactions/manage-transactions#cobo-defined-categories) 中说明。
+
+除 Fee Station 外，`AutoSweep` 是一个高频关键值，因为它标识自动资金归集交易。它可解释并非由显式 API 调用发起的余额变动。该枚举还包括 staking、screening、tokenization 以及其他类别。更完整的参考请参阅 [Cobo-defined categories](/v2_cn/guides/transactions/manage-transactions#cobo-defined-categories)。
+
+### `fueling_info`（仅 Fee Station）
+
+只有当交易存在关联的 Fee Station fueling 记录时，`fueling_info` 才会被填充；否则为 null。请将它与 `cobo_category`（尤其是 `AutoFueling`）结合使用，以把 Fee Station gas 交易关联到 fueling 请求和主交易。
+
+| 字段 | 说明 |
+|-------|-------------|
+| `request_id` | Fee Station fueling 请求标识符。 |
+| `transaction_id` | Fee Station 发起的 gas 或费用交易的交易 ID。 |
+| `main_transaction_id` | 需要 fueling 的主交易的交易 ID。只有当当前记录是 Fee Station 发起的 gas 或费用交易时，此字段才会被设置。 |
diff --git a/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx b/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx
new file mode 100644
index 00000000..95b81557
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx
@@ -0,0 +1,423 @@
+---
+title: "Transaction Webhook 负载示例"
+lang: "zh-hans"
+description: "展示充币、提币以及不同链和费用模型下 Transaction Webhook 事件负载的完整 JSON 示例。"
+sidebarTitle: "Transaction Webhook 负载示例"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文展示 `wallets.transaction.*` Webhook 事件中传递的完整 `Transaction` 数据类型负载。事件列表请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。完整的 `source` 和 `destination` 类型参考请参阅 [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations)。
+
+### 充币与提币
+
+以下原生币 EVM 充币使用 `source.source_type: DepositFromAddress` 和 `destination.destination_type: DepositToAddress`。`source` 表示资金来源，`destination.wallet_id` 标识接收钱包。
+
+```json
+{
+ "transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
+ "cobo_id": "20250701000101000000000000000000",
+ "request_id": null,
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Deposit",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": [
+ "0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"
+ ]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "1.25"
+ },
+ "result": {
+ "amount": "1.25",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 20,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x9f2c6d8e1a4b3c5d7e901234567890abcdef1234567890abcdef1234567890",
+ "raw_tx_info": {
+ "used_nonce": 9,
+ "raw_tx": "0xa22cb465..."
+ },
+ "replacement": null,
+ "description": null,
+ "created_timestamp": 1751328000000,
+ "updated_timestamp": 1751328060000,
+ "cobo_category": []
+}
+```
+
+Exchange Wallet 到 Exchange Wallet 的充币会在 `source` 中使用 `DepositFromWallet`，并在 `destination` 中使用 `DepositToWallet`，而不是上方示例中的地址类充币类型。
+
+以下代币提币使用钱包来源 `source` 和地址 `destination`。合约调用和消息签名目的地（例如 `EVM_Contract` 和 `EVM_EIP_191_Signature`）也使用同一个 `Transaction` 包装结构，但 `destination` 形态不同。更多目的地类型请参阅 [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations)。
+
+```json
+{
+ "transaction_id": "b3f2a891-6c4d-4e2a-8f1b-7d5e9c3a2f10",
+ "cobo_id": "20250701000102000000000000000000",
+ "request_id": "withdraw-20250701-0001",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Withdrawal",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "signer_key_share_holder_group_id": "9a0f5d51-3f7d-4d2f-9d7e-a514bf60f2c1"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
+ "amount": "100"
+ }
+ },
+ "result": {
+ "amount": "100",
+ "token_id": "ETH_USDT"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "65000",
+ "gas_used": "61234"
+ },
+ "confirmed_num": 18,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x1d3f5a7c9e0b2d4f6a8c01234567890abcdef1234567890abcdef12345678",
+ "raw_tx_info": {
+ "used_nonce": 10,
+ "raw_tx": "0x02f8b1..."
+ },
+ "replacement": null,
+ "description": "Customer withdrawal",
+ "created_timestamp": 1751328200000,
+ "updated_timestamp": 1751328260000,
+ "cobo_category": []
+}
+```
+
+### 费用模型
+
+对于使用 EIP-1559 的 EVM 交易，调试 nonce 处理或 RBF 行为时，请检查 `raw_tx_info.used_nonce` 和 `raw_tx_info.raw_tx`。
+
+```json
+{
+ "transaction_id": "c94d7e12-3a8b-4f6c-9e2d-1f8a5b6c7d34",
+ "cobo_id": "20250701000103000000000000000000",
+ "request_id": "eth-transfer-0001",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "signer_key_share_holder_group_id": "9a0f5d51-3f7d-4d2f-9d7e-a514bf60f2c1"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x742d35cc6634c0532925a3b844bc454e4438f44e",
+ "amount": "0.5"
+ }
+ },
+ "result": {
+ "amount": "0.5",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.002",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 16,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x2b4d6f8a0c1e3f5a7b9d01234567890abcdef1234567890abcdef12345678",
+ "raw_tx_info": {
+ "used_nonce": 9,
+ "raw_tx": "0xa22cb465..."
+ },
+ "replacement": null,
+ "created_timestamp": 1751328300000,
+ "updated_timestamp": 1751328360000,
+ "cobo_category": []
+}
+```
+
+对于 UTXO 交易，`source.included_utxos` 表示请求中指定的输入（如有），`raw_tx_info.selected_utxos` 表示广播交易实际选择的输入。
+
+```json
+{
+ "transaction_id": "d1e8f423-9b6a-4c3d-8e1f-2a7b9c5d6e48",
+ "cobo_id": "20250701000104000000000000000000",
+ "request_id": "btc-transfer-0001",
+ "wallet_id": "6d9f3b29-7841-4b10-85f2-a674dc371ad1",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "BTC",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "6d9f3b29-7841-4b10-85f2-a674dc371ad1",
+ "address": "bc1qsourceaddress000000000000000000000000",
+ "included_utxos": [
+ {
+ "tx_hash": "6f1c9a2b3d4e5f678901234567890abcdef1234567890abcdef1234567890",
+ "vout_n": 0
+ }
+ ]
+ },
+ "destination": {
+ "destination_type": "Address",
+ "utxo_outputs": [
+ {
+ "address": "bc1qdestination000000000000000000000000000",
+ "amount": "0.01"
+ }
+ ]
+ },
+ "result": {
+ "amount": "0.01",
+ "token_id": "BTC"
+ },
+ "fee": {
+ "fee_type": "UTXO",
+ "token_id": "BTC",
+ "fee_used": "0.00015",
+ "fee_rate": "50",
+ "max_fee_amount": "0.0002"
+ },
+ "confirmed_num": 6,
+ "confirming_threshold": 3,
+ "transaction_hash": "4b8e1d6c9f2a34567890abcdef1234567890abcdef1234567890abcdef12",
+ "raw_tx_info": {
+ "selected_utxos": [
+ {
+ "tx_hash": "6f1c9a2b3d4e5f678901234567890abcdef1234567890abcdef1234567890",
+ "vout_n": 0,
+ "token_id": "BTC",
+ "address": "bc1qsourceaddress000000000000000000000000"
+ }
+ ],
+ "utxo_changes": [
+ {
+ "address": "bc1qchangeaddress0000000000000000000000000",
+ "value": "0.00485",
+ "token_id": "BTC"
+ }
+ ]
+ },
+ "replacement": null,
+ "created_timestamp": 1751328400000,
+ "updated_timestamp": 1751328460000,
+ "cobo_category": []
+}
+```
+
+UTXO 找零输出的 schema 字段是 `utxo_changes`，这是一个复数数组。单数字段 `utxo_change` 已弃用，不应在新示例或集成中使用。
+
+TRON 风格交易使用 Fixed 费用模型。TRON 及类似链使用的 Fixed 费用模型没有 gas 或 priority fee 子字段，只包含 `token_id`、`fee_used`、`estimated_fee_used` 和 `max_fee_amount`。
+
+```json
+{
+ "transaction_id": "e5a3b678-2c9d-4f1e-8b6a-3d7c8e9f1a52",
+ "cobo_id": "20250701000105000000000000000000",
+ "request_id": "tron-transfer-0001",
+ "wallet_id": "22fb96d7-5d43-4af5-bb8f-c2bb0f57f4a2",
+ "type": "Withdrawal",
+ "status": "Success",
+ "token_id": "TRON_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "22fb96d7-5d43-4af5-bb8f-c2bb0f57f4a2",
+ "address": "TSourceAddress111111111111111111111111"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "TDestination1111111111111111111111111",
+ "amount": "50"
+ }
+ },
+ "result": {
+ "amount": "50",
+ "token_id": "TRON_USDT"
+ },
+ "fee": {
+ "fee_type": "Fixed",
+ "token_id": "TRON",
+ "fee_used": "0.1",
+ "estimated_fee_used": "0.1",
+ "max_fee_amount": "0.2"
+ },
+ "confirmed_num": 20,
+ "confirming_threshold": 19,
+ "transaction_hash": "9abf1c2d3e4f567890abcdef1234567890abcdef1234567890abcdef1234",
+ "raw_tx_info": null,
+ "replacement": null,
+ "created_timestamp": 1751328500000,
+ "updated_timestamp": 1751328560000,
+ "cobo_category": []
+}
+```
+
+### Fee Station 交易
+
+`fee_station.transaction.*` 事件传递的 `Transaction` 负载 schema 与 `wallets.transaction.*` 事件相同。Fee Station 变体使用 `fee_station.` 事件类型前缀，并从 `wallet_scopes_info` 中省略钱包范围元数据字段。
+
+`type` 字段不会区分 Fee Station 交易。内部 Fee Station 查询类型会在负载返回前映射为公开的 `Deposit` 或 `Withdrawal` 值。
+
+以下 AutoFueling 示例使用相同的 `Transaction` 包装结构，并包含 Fee Station 专属的 `cobo_category` 和 `fueling_info` 值。
+
+```json
+{
+ "transaction_id": "f6b7c8d9-0a1b-4c2d-9e3f-456789abcdef",
+ "cobo_id": "20250701000106000000000000000000",
+ "request_id": null,
+ "wallet_id": "fee-station-wallet-001",
+ "type": "Withdrawal",
+ "status": "Success",
+ "sub_status": null,
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "Org-Controlled",
+ "wallet_id": "fee-station-wallet-001",
+ "address": "0xfee0000000000000000000000000000000000001"
+ },
+ "destination": {
+ "destination_type": "Address",
+ "account_output": {
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "0.05"
+ }
+ },
+ "result": {
+ "amount": "0.05",
+ "token_id": "ETH"
+ },
+ "fee": {
+ "fee_type": "EVM_EIP_1559",
+ "token_id": "ETH",
+ "fee_used": "0.001",
+ "max_fee_per_gas": "9000000000000",
+ "max_priority_fee_per_gas": "1000000000000",
+ "gas_limit": "21000",
+ "gas_used": "21000"
+ },
+ "confirmed_num": 15,
+ "confirming_threshold": 12,
+ "transaction_hash": "0x6c7d8e9f01234567890abcdef1234567890abcdef1234567890abcdef1234",
+ "raw_tx_info": {
+ "used_nonce": 11,
+ "raw_tx": "0x02f901..."
+ },
+ "replacement": null,
+ "description": "AutoFueling transaction",
+ "created_timestamp": 1751328600000,
+ "updated_timestamp": 1751328660000,
+ "cobo_category": ["AutoFueling"],
+ "fueling_info": {
+ "request_id": "fuel-20250701-0001",
+ "transaction_id": "f6b7c8d9-0a1b-4c2d-9e3f-456789abcdef",
+ "main_transaction_id": "b3f2a891-6c4d-4e2a-8f1b-7d5e9c3a2f10"
+ }
+}
+```
+
+请使用 `cobo_category` 识别 Fee Station 专属交易类别。这些取值已在 [Cobo-defined categories](/v2_cn/guides/transactions/manage-transactions#cobo-defined-categories) 中说明。
+
+### 原生币、代币与 Exchange Wallet asset_id
+
+对于 MPC Wallet、Custodial Wallet 和 Smart Contract Wallet 交易，请使用 `token_id` 标识币种或代币。即使是代币交易，`asset_id` 也为空或不存在。
+
+```json
+[
+ {
+ "type": "Deposit",
+ "token_id": "ETH",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": ["0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "1.25"
+ }
+ },
+ {
+ "type": "Deposit",
+ "token_id": "ETH_USDT",
+ "asset_id": null,
+ "source": {
+ "source_type": "DepositFromAddress",
+ "wallet_type": "MPC",
+ "addresses": ["0x7d4e9f2b6a1c3d8e5f901234567890abcdef1234"]
+ },
+ "destination": {
+ "destination_type": "DepositToAddress",
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "amount": "100"
+ }
+ },
+ {
+ "type": "Withdrawal",
+ "token_id": "TRON_USDT",
+ "asset_id": "USDT",
+ "source": {
+ "source_type": "Main",
+ "exchange_id": "binance-main"
+ },
+ "destination": {
+ "destination_type": "ExchangeWallet",
+ "exchange_id": "okx-main"
+ }
+ }
+]
+```
+
+此数组仅保留与 `token_id` 和 `asset_id` 对比相关的字段，并不是完整的 `Transaction` 负载。完整的 `Transaction` 负载包含完整的 `source` 和 `destination` 对象，如上方完整示例所示。
+
+只有当涉及的钱包是 Exchange Wallet 时，`asset_id` 才会被填充。对于其他所有钱包类型，`asset_id` 都不存在或为 null。更多详情请参阅 [`token_id` vs. `asset_id`](/v2_cn/guides/webhooks-callbacks/transaction-field-dictionary#token_id-vs-asset_id)。
diff --git a/v2_cn/guides/webhooks-callbacks/tss-request-field-dictionary.mdx b/v2_cn/guides/webhooks-callbacks/tss-request-field-dictionary.mdx
new file mode 100644
index 00000000..19ed9560
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/tss-request-field-dictionary.mdx
@@ -0,0 +1,44 @@
+---
+title: "TSS request 负载字段词典"
+lang: "zh-hans"
+description: "定义 TSSRequest Webhook 负载中的字段和触发行为。"
+sidebarTitle: "TSS request 字段词典"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文定义 `wallets.mpc.tss_request.*` Webhook 事件使用的高频 `TSSRequest` 字段。Webhook 负载与已记录的 `TSSRequest` schema 完全一致，没有额外字段或遗漏字段。
+
+### Request type
+
+| 值 | 说明 |
+|-------|-------------|
+| `KeyGen` | 创建新的 key share holder group。 |
+| `KeyGenFromKeyGroup` | 从已有 key group 创建新的 key share holder group。 |
+| `Recovery` | 恢复或重组已有 key share holder group。 |
+
+这些值由 `TSSRequest` schema 定义。
+
+### Request status
+
+| 值 | 说明 |
+|-------|-------------|
+| `PendingKeyHolderConfirmation` | 请求正在等待足够的 key share holder 批准。 |
+| `KeyHolderConfirmationFailed` | key share holder 未能批准该 TSS request 的操作。 |
+| `KeyGenerating` | 正在为该 TSS request 的操作生成 key share。 |
+| `MPCProcessing` | TSS request 审批正在等待开始或正在进行中。 |
+| `KeyGeneratingFailed` | 该 TSS request 操作的 key share 生成流程失败。 |
+| `Success` | 请求已成功完成。 |
+
+这些值由 `TSSRequest` schema 定义。
+
+### Event trigger behavior
+
+| Event type | Trigger |
+|------------|---------|
+| `wallets.mpc.tss_request.created` | 请求新建或进入 new-request 状态。 |
+| `wallets.mpc.tss_request.succeeded` | 请求状态变为 `Success`。 |
+| `wallets.mpc.tss_request.failed` | 请求进入最终失败状态。 |
+| `wallets.mpc.tss_request.updated` | 其他受支持的状态转换。该 fallback 仅限 portal key generation 和 reshare 请求。 |
diff --git a/v2_cn/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx b/v2_cn/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx
new file mode 100644
index 00000000..6de052bb
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/tss-request-webhook-payload-examples.mdx
@@ -0,0 +1,50 @@
+---
+title: "TSS request Webhook 负载示例"
+lang: "zh-hans"
+description: "展示 MPC key generation 和 recovery 请求的 TSSRequest Webhook 事件负载完整 JSON 示例。"
+sidebarTitle: "TSS request Webhook 负载示例"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文展示 `wallets.mpc.tss_request.*` Webhook 事件中传递的完整 `TSSRequest` 数据类型负载。事件列表请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。
+
+### KeyGen request created
+
+`KeyGen` 请求可以携带 `source_key_share_holder_group: null`。该字段在 `KeyGen` 请求中为空，并为 reshare 或 migrate 类请求填充。
+
+```json
+{
+ "tss_request_id": "tss-req-20250701-0001",
+ "source_key_share_holder_group": null,
+ "target_key_share_holder_group_id": "kshg-target-001",
+ "type": "KeyGen",
+ "status": "PendingKeyHolderConfirmation",
+ "description": "Create an MPC key share holder group",
+ "created_timestamp": 1751328000000
+}
+```
+
+### Recovery request succeeded
+
+对于 `Recovery` 请求，`source_key_share_holder_group` 标识 source key share holder group，以及该 source group 中包含的 TSS Node ID。
+
+```json
+{
+ "tss_request_id": "tss-req-20250701-0002",
+ "source_key_share_holder_group": {
+ "key_share_holder_group_id": "kshg-source-001",
+ "tss_node_ids": [
+ "tss-node-001",
+ "tss-node-002"
+ ]
+ },
+ "target_key_share_holder_group_id": "kshg-target-002",
+ "type": "Recovery",
+ "status": "Success",
+ "description": "Recover an MPC key share holder group",
+ "created_timestamp": 1751328600000
+}
+```
diff --git a/v2_cn/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx b/v2_cn/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx
new file mode 100644
index 00000000..2365ef10
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/wallet-address-field-dictionary.mdx
@@ -0,0 +1,34 @@
+---
+title: "Wallet 和 address 负载字段词典"
+lang: "zh-hans"
+description: "定义 wallet、address 和 MPC vault Webhook 负载字段及集成注意事项。"
+sidebarTitle: "Wallet 和 address 字段词典"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文定义 wallet 和 address management Webhook 事件使用的高频字段。
+
+### `addresses`
+
+`addresses` 是已创建 wallet address 的数组。单个地址创建事件也使用同一个数组包装结构。每个条目包含 `wallet_id` 以及 `AddressInfo` 字段 `address`、`chain_id`、`memo`、`path`、`encoding`、`pubkey`、`x_only_pubkey`、`root_pubkey`、`taproot_script_tree_hash`、`taproot_internal_address` 和 `stellar_trusted_token_ids`。
+
+对于 Solana Associated Token Account 激活，请参阅 [钱包与地址管理事件](/v2_cn/guides/webhooks-callbacks/webhook-event-type#wallet-and-address-management-events) 中的 note。
+
+### `WalletInfo`
+
+`WalletInfo` 是按 wallet type 选择的 oneOf 负载。该派发路径在各 wallet type 间共享，包括 MPC vault-wallet 和 Custodial wallet 创建。
+
+| 字段 | 说明 |
+|-------|-------------|
+| `wallet_id` | 已创建 wallet 的标识符。 |
+| `wallet_type` | wallet family，例如 `MPC`，用于决定返回哪个 oneOf branch。 |
+| `wallet_subtype` | wallet family 内的 subtype，例如 `Org-Controlled`。 |
+| `vault_id` | 对于 `MPCWalletInfo` 负载，表示拥有该 wallet 的 MPC vault。 |
+| `project_id` | 对于 `MPCWalletInfo` 负载，表示与该 wallet 关联的 project。 |
+
+### `MPCVault`
+
+`MPCVault` 标识已创建 vault 及其生成的 root public key。`root_pubkeys` 是包含 `root_pubkey` 和 `curve` 的 `RootPubkey` 对象数组，而不是字符串数组。
diff --git a/v2_cn/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx b/v2_cn/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx
new file mode 100644
index 00000000..b4bcb322
--- /dev/null
+++ b/v2_cn/guides/webhooks-callbacks/wallet-address-webhook-payload-examples.mdx
@@ -0,0 +1,90 @@
+---
+title: "Wallet 和 address Webhook 负载示例"
+lang: "zh-hans"
+description: "展示 wallet、address 和 MPC vault 管理 Webhook 事件负载的完整 JSON 示例。"
+sidebarTitle: "Wallet 和 address 负载示例"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+
+
+
+本文展示 wallet 和 address management Webhook 事件的完整负载示例。事件列表请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。
+
+### Address creation
+
+`wallets.addresses.created` 传递 `Addresses` 负载。它会在单个地址创建和批量地址创建时触发，`addresses` 数组会包含该批次中创建的所有地址。
+
+```json
+{
+ "addresses": [
+ {
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "0x5aeda56215b167893e80b4fe645ba6d5bab767de",
+ "chain_id": "ETH",
+ "memo": null,
+ "path": "m/44'/60'/0'/0/0",
+ "encoding": null,
+ "pubkey": "03f0288924f1c...",
+ "x_only_pubkey": null,
+ "root_pubkey": "xpub6CUGRU...",
+ "taproot_script_tree_hash": null,
+ "taproot_internal_address": null,
+ "stellar_trusted_token_ids": []
+ },
+ {
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "address": "bc1qexampleaddress0000000000000000000000000",
+ "chain_id": "BTC",
+ "memo": null,
+ "path": "m/84'/0'/0'/0/0",
+ "encoding": "ENCODING_BECH32",
+ "pubkey": "02c6047f9441ed...",
+ "x_only_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
+ "root_pubkey": "xpub6DExample...",
+ "taproot_script_tree_hash": null,
+ "taproot_internal_address": "bc1pinternaladdress000000000000000000000000",
+ "stellar_trusted_token_ids": []
+ }
+ ]
+}
+```
+
+### Wallet creation
+
+`wallets.created` 传递 `WalletInfo` 负载。Webhook 从适用于多种 wallet type 的共享 wallet 创建路径发出，负载变体与 wallet type 相匹配。
+
+```json
+{
+ "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+ "wallet_type": "MPC",
+ "wallet_subtype": "Org-Controlled",
+ "name": "Treasury MPC Wallet",
+ "vault_id": "vault-20250701-001",
+ "project_id": "project-20250701-001"
+}
+```
+
+### MPC vault creation
+
+`mpc_vaults.created` 传递 `MPCVault` 负载。它会针对 Org-Controlled 和 User-Controlled vault 触发，并且 `root_pubkeys` 是对象列表，而不是纯字符串列表。
+
+```json
+{
+ "vault_id": "vault-20250701-001",
+ "project_id": "project-20250701-001",
+ "name": "Treasury MPC Vault",
+ "type": "Org-Controlled",
+ "root_pubkeys": [
+ {
+ "root_pubkey": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...",
+ "curve": "SECP256K1"
+ },
+ {
+ "root_pubkey": "xpub6DExampleRootPubkeyForEd25519...",
+ "curve": "ED25519"
+ }
+ ],
+ "created_timestamp": 1751328000000
+}
+```
diff --git a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
index 4653ec1e..522fca2c 100644
--- a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
+++ b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
@@ -64,6 +64,16 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+如需查看 `Transaction` 数据类型的完整示例负载，请参阅 [Transaction Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples)。
+
+只有 `wallets.transaction.succeeded` 事件表示交易已成功完成。这是唯一可安全用于触发充币入账的 Transaction 事件。`wallets.transaction.updated` 会在交易整个生命周期中的每次状态变化时触发，包括交易确认前甚至广播前的状态，因此不得用于入账。请仅将其用于状态或 UI 跟踪。Confirming 阶段通知同样只表示进度，不表示完成。请等待 `wallets.transaction.succeeded`，或轮询 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 并确认 `status: Success` 后，再为充币入账。
+
+### Callback 阶段的 transaction 负载
+
+发送 Callback 消息时，其 `Transaction` 负载使用与 Webhook 事件和查询 API 负载相同的 schema。Webhook 和 Callback 的区别请参阅 [Webhooks vs callbacks](/v2_cn/guides/webhooks-callbacks/introduction#webhooks-vs-callbacks)。
+
+由于 Callback 在您发起提币或合约调用时触发，也就是交易广播到链上或确认之前，因此该负载中的若干字段尚未填充。Callback 阶段最常见的未填充字段包括 `cobo_id`、`asset_id`、`result`、`confirmed_num` 和 `confirming_threshold`，因为它们代表的值（例如链上广播跟踪 ID、Exchange 资产记账、执行结果和确认数）需要等交易广播并开始确认后才会出现。`cobo_category` 在此阶段也可能为空。这些是常见示例；schema 中的 nullable 字段通常也可能因交易阶段不同而为空。
+
### Fee Station 相关事件
@@ -99,6 +109,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+如需查看 Fee Station `Transaction` 数据类型的完整示例负载，请参阅 [Fee Station 交易](/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples#fee-station-交易)。
+
### MPC 钱包 TSS 请求事件
@@ -133,6 +145,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+如需查看 `TSSRequest` 数据类型的完整示例负载，请参阅 [TSS request Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/tss-request-webhook-payload-examples)。
+
### 钱包与地址管理事件
@@ -164,6 +178,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
激活 Solana 代币子地址（Associated Token Account）不会触发 `wallets.addresses.created` 事件。为激活该地址而发生的租金转账也不会触发任何 `wallets.transaction.*` 事件，且不会生成充币或交易记录。因此，Solana 代币账户的激活及其租金无法通过 webhook 感知。详情请参阅 [Solana 代币账户租金](/v2_cn/guides/transactions/solana-token-account-rent)。
+如需查看 `Addresses`、`WalletInfo` 和 `MPCVault` 数据类型的完整示例负载，请参阅 [Wallet 和 address Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/wallet-address-webhook-payload-examples)。
+
### 代币与链管理事件
@@ -208,6 +224,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+如需查看 `Tokens`、`Chains` 和 `TokenListing` 数据类型的完整示例负载，请参阅 [Token 和 chain Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/token-chain-webhook-payload-examples)。
+
### 余额更新事件
@@ -232,6 +250,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+如需查看 `BalanceUpdateInfo` 数据类型的完整示例负载，请参阅 [Balance update Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/balance-update-webhook-payload-examples)。
+
### 合规事件
@@ -256,6 +276,42 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
+### `ComplianceDisposition` 事件数据
+
+`compliance.disposition.status.updated` 事件用于通知你某笔交易的 compliance disposition 状态已发生变化。`ComplianceDisposition` 负载包含 `transaction_id`、`disposition_type`、`disposition_status`、`destination_address`、`disposition_amount` 和 `updated_timestamp`。
+
+当你所在机构的 Screening App 集成报告 disposition 状态变化时，Cobo 会发出此事件。由于该更新来自 Screening App，请将其视为该服务记录的当前 disposition 状态，而不是 Cobo 在本地计算的状态。使用 `transaction_id` 将事件与调用 [Refund funds](/v2/api-references/compliance/refund-funds)、[Isolate funds](/v2/api-references/compliance/isolate-funds) 或 [Unfreeze frozen funds](/v2/api-references/compliance/unfreeze-frozen-funds) 时所针对的交易相关联。
+
+**`disposition_type`（`DispositionType`）**
+
+| 值 | 含义 |
+|-------|---------|
+| `Refund` | 该 disposition 由调用 [Refund funds](/v2/api-references/compliance/refund-funds) 创建。 |
+| `Isolate` | 该 disposition 由调用 [Isolate funds](/v2/api-references/compliance/isolate-funds) 创建。 |
+| `Unfreeze` | 该 disposition 由调用 [Unfreeze frozen funds](/v2/api-references/compliance/unfreeze-frozen-funds) 创建。 |
+
+每项操作都会将 disposition 请求提交到你所在机构的 Screening App 集成进行处理。
+
+**`disposition_status`（`DispositionStatus`）**
+
+| 值 | 含义 |
+|-------|---------|
+| `Submitted` | disposition request 已提交。 |
+| `Refunding` | 资金退款正在进行中。 |
+| `Refunded` | 资金已退款。 |
+| `RefundFailed` | 退款尝试失败。 |
+| `Frozen` | 相关资金已被冻结。 |
+| `Unfreezing` | 资金正在解冻中。 |
+| `Unfrozen` | 资金已解冻。 |
+| `UnfreezeFailed` | 资金解冻尝试失败。 |
+| `Isolating` | 资金正在隔离中。 |
+| `Isolated` | 资金已隔离。 |
+| `IsolateFailed` | 资金隔离尝试失败。 |
+| `CoboDisposition` | 资金正在通过 Cobo disposition 处理。 |
+| `Normal` | 资金处于正常状态，未应用任何合规操作。 |
+
+收到此事件后，请以 `transaction_id` 为键，将报告的 `disposition_type` 和 `disposition_status` 记录为该交易 disposition 状态的增量更新。要随时确认当前 disposition 状态（例如在决定后续操作之前），请针对该交易调用 [Get disposition status](/v2/api-references/compliance/get-disposition-status)。
+
### `ComplianceKytScreenings` 事件数据
`compliance.kyt.screenings.status.updated` 事件携带 `ComplianceKytScreenings` 负载（`KytScreeningsEventData`）。该负载报告两个独立的状态字段 `review_status` 和 `funds_status`。请分别跟踪它们：`review_status` 反映案件的扫描与审核进度，`funds_status` 反映相关资金的状态。
@@ -295,8 +351,10 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
## Webhook 事件数据结构
有关 webhook 事件数据和其数据结构的完整介绍，请参阅 Retrieve event information 操作的响应中的 [data](/v2/api-references/developers--webhooks/retrieve-event-information#response-data) 属性或 List all webhook events 操作的响应中的 [data.data](/v2/api-references/developers--webhooks/list-all-webhook-events#response-data-data) 属性。
+如需查看覆盖充币、提币以及不同链的 `Transaction` 数据类型完整 JSON 示例，请参阅 [Transaction Webhook 负载示例](/v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples)。
+
您可以在事件数据类型之间切换来查看每个事件数据类型的数据结构。
-另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。
\ No newline at end of file
+另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。