diff --git a/docs.json b/docs.json index 1a46808e..33d96f66 100644 --- a/docs.json +++ b/docs.json @@ -46,13 +46,16 @@ "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-events", + "v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events" ] }, { "group": "Transactions", "pages": [ "v2/guides/transactions/sources-and-destinations", + "v2/guides/transactions/transaction-fields", "v2/guides/transactions/transfer-routing", "v2/guides/transactions/estimate-fees", "v2/guides/transactions/solana-token-account-rent", @@ -858,13 +861,16 @@ "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-events", + "v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events" ] }, { "group": "交易", "pages": [ "v2_cn/guides/transactions/sources-and-destinations", + "v2_cn/guides/transactions/transaction-fields", "v2_cn/guides/transactions/transfer-routing", "v2_cn/guides/transactions/estimate-fees", "v2_cn/guides/transactions/solana-token-account-rent", @@ -1598,4 +1604,4 @@ "destination": "https://www.cobo.com/payments/cn/guides/overview" } ] -} \ No newline at end of file +} diff --git a/v2/guides/transactions/transaction-fields.mdx b/v2/guides/transactions/transaction-fields.mdx new file mode 100644 index 00000000..ad41ac1c --- /dev/null +++ b/v2/guides/transactions/transaction-fields.mdx @@ -0,0 +1,126 @@ +--- +title: "Transaction fields" +lang: "en" +description: "Reference the Transaction object returned by transaction API operations and delivered in transaction webhook events and callback messages." +sidebarTitle: "Transaction fields" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +The `Transaction` object represents a transaction throughout its lifecycle. Transaction API operations, transaction webhook events, and callback messages use this object. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
transaction_idstringCobo's unique identifier for the transaction.
cobo_idstringThe Cobo ID that you can use to track the transaction.
request_idstringYour unique identifier for the API request that initiated the transaction. It is absent when no corresponding request exists, such as for a deposit.
wallet_idstringThe unique identifier of the wallet associated with the transaction.
typestringThe transaction type, such as Deposit, Withdrawal, ContractCall, or MessageSign.
statusstringThe transaction's lifecycle stage.
sub_statusstringA more specific reason or stage within status.
failed_reasonstringAdditional detail about why the transaction failed.
chain_idstringThe unique identifier of the blockchain on which the transaction occurs.
token_idstringThe WaaS token catalog identifier for Custodial Wallet, Web3 Wallet, and MPC Wallet transactions.
asset_idstringThe asset identifier in your linked exchange account. It applies only to Exchange Wallet transactions.
sourceobjectThe transaction origin. Its shape is selected by source_type.
destinationobjectThe transaction target or signing input. Its shape is selected by destination_type.
resultobjectThe signing result for a MessageSign transaction. It is absent for every other transaction type.
feeobjectThe network fee details, discriminated by fee_type. It is populated after broadcast and absent while signature or broadcast is pending.
initiatorstringThe name or identifier of the transaction initiator.
initiator_typestringThe channel through which the transaction was initiated.
confirmed_numintegerThe number of confirmations received.
confirming_thresholdintegerThe minimum confirmation count required by Cobo.
transaction_hashstringThe on-chain transaction identifier, also called the transaction hash or txid. It is populated only after broadcast.
block_infoobjectThe number, timestamp, and hash of the confirmed block. It is absent before on-chain confirmation and for MessageSign transactions.
raw_tx_infoobjectThe constructed transaction data and any nonce or UTXO details. It is populated after assembly for broadcast and is absent before that stage and for MessageSign transactions.
replacementobjectForward or backward links between an original transaction and its replacement. It appears only when a replacement operation exists.
categoryarray of stringsYour custom categories for organizing transactions.
descriptionstringYour description of the transaction.
is_loopbooleanWhether the transaction was executed as a Cobo Loop transfer.
cobo_categoryarray of stringsSystem-assigned categories that identify Cobo workflows associated with the transaction.
extraarray of stringsJSON-encoded, business-specific information; each item identifies its shape with extra_type.
fueling_infoobjectFee Station fueling details associated with the transaction.
created_timestampintegerThe creation time as a Unix timestamp in milliseconds.
updated_timestampintegerThe most recent update time as a Unix timestamp in milliseconds.
+ +For the complete status and sub-status values, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status). + +## `token_id` and `asset_id` + +`token_id` is the token's identifier in the WaaS token catalog, such as `ETH`, `ETH_USDT`, or `BTC`. Use [List enabled tokens](/v2/api-references/wallets/list-enabled-tokens) to retrieve the identifiers available to your organization. + +`token_id` is populated for Custodial Wallet, Web3 Wallet, and MPC Wallet transactions. `asset_id` is the asset identifier in your linked exchange account and is populated only for Exchange Wallet transactions. A transaction has one field or the other based on its wallet type, not both. The fields are not interchangeable. + +## `request_id` + +`request_id` is present only for transactions that you initiated through an API request, such as a transaction-creation operation. Use it to correlate the transaction with your original request. It is absent for deposits and other transactions that Cobo created without a corresponding request from you. + +## `replacement` and RBF links + +The `replacement` object links transactions involved in replacement operations: + +| Field | Description | +|-------|-------------| +| `replaced_by_type` | The replacement operation applied to the original transaction: `Drop`, `Resend`, or `SpeedUp`. | +| `replaced_by_transaction_id` | The Cobo transaction ID of the transaction that replaced this transaction. | +| `replaced_by_transaction_hash` | The on-chain hash of the transaction that replaced this transaction. | +| `replaced_type` | The replacement operation through which this transaction replaced another transaction. | +| `replaced_transaction_id` | The Cobo transaction ID of the transaction replaced by this transaction. | +| `replaced_transaction_hash` | The on-chain hash of the transaction replaced by this transaction. | + +See [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle) for replacement operations and status changes. + +`replaced_by_transaction_hash` is populated only after the replacing transaction from a `Drop`, `Resend`, or `SpeedUp` operation has broadcast. Use it together with `replaced_by_transaction_id` to look up the replacing transaction. + +## `cobo_category` + +`cobo_category` is assigned by Cobo and is distinct from your `category` and `description` values. Examples include `AutoFueling`, `BillPayment`, and `AutoSweep`. See [Cobo-defined categories](/v2/guides/transactions/manage-transactions#cobo-defined-categories) for the categorized value list. + +## Structured and conditional fields + +### `fee` + +`fee` is populated after the transaction broadcasts. It is absent while signature or broadcast is pending. + +The `fee_type` discriminator selects the fee shape for the chain's fee model: `EVM_EIP_1559`, `EVM_Legacy`, `UTXO`, `Fixed`, `SOL`, or `FIL`. Fee shapes can include the fee token in `token_id`, the charged amount in `fee_used`, and the estimate in `estimated_fee_used`. Chain-specific shapes add fields such as gas prices and gas usage, UTXO fee rates, Solana compute units, or Filecoin gas parameters. See [Estimate transaction fees](/v2/guides/transactions/estimate-fees) for fee models. + +### `block_info` + +`block_info` is populated after the transaction broadcasts and receives on-chain confirmation. It is absent for pending transactions and for `MessageSign` transactions. + +`block_info` contains: + +| Field | Description | +|-------|-------------| +| `block_number` | The number of the block containing the transaction. | +| `block_timestamp` | The block creation time as a Unix timestamp in milliseconds. | +| `block_hash` | The block's hash. | + +### `raw_tx_info` + +`raw_tx_info` is populated after the transaction has been assembled for broadcast. It is absent before that stage and for `MessageSign` transactions. + +`raw_tx_info` contains constructed transaction data: + +| Field | Description | +|-------|-------------| +| `used_nonce` | The nonce used by the transaction. | +| `selected_utxos` | The inputs selected for a UTXO transaction. Each item can include `tx_hash`, `vout_n`, `token_id`, `address`, and `value`, plus script or object-chain details when applicable. | +| `raw_tx` | The serialized raw transaction. | +| `unsigned_raw_tx` | The serialized transaction before signing. | +| `utxo_changes` | UTXO change outputs. Each item contains `address`, `value`, and `token_id`. | + +### `result` + +`result` is present only for `MessageSign` transactions. For a message-signing result, `result_type` is `Signature` and `signature` contains the raw signature data. + +## Sources and destinations + +`source` and `destination` are discriminated objects. `source_type` identifies the wallet or deposit origin, while `destination_type` identifies an address, wallet, contract call, deposit target, or message-signing format. See [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) for the complete fields supported by each transaction type. diff --git a/v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx b/v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx new file mode 100644 index 00000000..8150149d --- /dev/null +++ b/v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx @@ -0,0 +1,94 @@ +--- +title: "MPC TSS request webhook events" +lang: "en" +description: "Understand the payload and lifecycle signals for wallets.mpc.tss_request.* webhook events." +sidebarTitle: "MPC TSS request webhook events" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +The `wallets.mpc.tss_request.*` webhook events report Cobo Portal key-generation and reshare operations for MPC Wallets. `KeyGen` creates the organization's first Main Group. `KeyGenFromKeyGroup` derives a new Signing Group or Recovery Group from an existing Main Group. `Recovery` replaces a holder's key share within the Main Group. + +## Event lifecycle + + + + + + + + + +
EventData typeWhen it occurs
wallets.mpc.tss_request.createdTSSRequestFires once when the request is created, before any key-holder interaction.
wallets.mpc.tss_request.updatedTSSRequestFires for each subsequent intermediate status change, including key-holder confirmation, key generation, and MPC processing states.
wallets.mpc.tss_request.succeededTSSRequestFires once when the request reaches the terminal Success status.
wallets.mpc.tss_request.failedTSSRequestFires once when the request reaches a terminal failure state and cannot proceed.
+ +Intermediate statuses such as `PendingKeyHolderConfirmation`, `KeyHolderConfirmationFailed`, `KeyGenerating`, and `MPCProcessing` are delivered through `updated`, not through terminal events. The initial request state is delivered through `created`; terminal outcomes are delivered through `succeeded` or `failed`. + +## Payload reference + +| Field | Type | Description | +|-------|------|-------------| +| `tss_request_id` | string | The unique identifier of the TSS request. | +| `source_key_share_holder_group` | object | The existing source group. It is populated for `KeyGenFromKeyGroup` and `Recovery` and absent for `KeyGen`, which has no prior group. | +| `target_key_share_holder_group_id` | string | The target group for every request type: the new Main Group for `KeyGen`, the derived Signing or Recovery Group for `KeyGenFromKeyGroup`, or the Main Group whose member key share is replaced for `Recovery`. | +| `type` | string | The request type: `KeyGen`, `KeyGenFromKeyGroup`, or `Recovery`. | +| `status` | string | The current TSS request lifecycle status. | +| `description` | string | The description supplied for the TSS request. | +| `created_timestamp` | integer | The request creation time as a Unix timestamp in milliseconds. | + +When provided, `source_key_share_holder_group` contains: + +| Field | Type | Description | +|-------|------|-------------| +| `key_share_holder_group_id` | string | The identifier of the source key share holder group. | +| `tss_node_ids` | array of strings | The TSS Node IDs participating in creation of the new key share holder group. | + +The following examples show all four outcomes. Each object includes every field populated for the represented request. + +### Created + +```json +{ + "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f", + "url": "https://example.com/webhook", + "created_timestamp": 1701396866000, + "type": "wallets.mpc.tss_request.created", + "data": { + "data_type": "TSSRequest", + "tss_request_id": "20240711114129000132315000003970", + "target_key_share_holder_group_id": "fd9519ae-507b-4605-b108-04d4e5ffcdd3", + "type": "KeyGen", + "status": "PendingKeyHolderConfirmation", + "description": "Create the first Main Group", + "created_timestamp": 1701396866000 + }, + "status": "Delivered" +} +``` + +### Updated + +```json +{"event_id":"event-tss-updated","url":"https://example.com/webhook","created_timestamp":1701396966000,"type":"wallets.mpc.tss_request.updated","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"MPCProcessing","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +### Succeeded + +```json +{"event_id":"event-tss-succeeded","url":"https://example.com/webhook","created_timestamp":1701397066000,"type":"wallets.mpc.tss_request.succeeded","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"Success","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +### Failed + +```json +{"event_id":"event-tss-failed","url":"https://example.com/webhook","created_timestamp":1701397166000,"type":"wallets.mpc.tss_request.failed","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003972","target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd4","type":"KeyGen","status":"KeyGeneratingFailed","description":"Create the first Main Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +See [Set up a callback or webhook endpoint](/v2/guides/webhooks-callbacks/set-up-endpoint) for delivery and retry behavior. + +## Related guides + +- [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type) diff --git a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx index 4153a322..e7ee9195 100644 --- a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx +++ b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx @@ -100,6 +100,37 @@ When your callback endpoint receives a callback message, it should respond with If the callback endpoint does not respond, responds with a status code other than `200` or `201`, or the response body does not contain `ok` or `deny`, the WaaS service will continue to retry sending the message. If the number of retry attempts reaches 30, the WaaS service will stop sending the message and the callback message status will become `Failed`. You can resend the message by using the [Retry callback message](/v2/api-references/developers/retry-callback-message) operation. +### Callback message payload + +A callback message's `data` field uses the `Transaction` object. It represents the transaction at the point when your callback endpoint must return `ok` or `deny`, so do not treat it as the final transaction state. Later transaction webhook events use the same object as the transaction progresses. + +Use [Transaction fields](/v2/guides/transactions/transaction-fields) for the complete field dictionary, including `cobo_id`, `request_id`, `token_id`, `asset_id`, `result`, `fee`, `transaction_hash`, `block_info`, `raw_tx_info`, and `replacement`. When processing a callback, base your decision on the values present in that callback message. Retrieve the transaction or process a later transaction webhook event when you need its subsequent state. + +| Field | Callback phase | Later transaction phase | +|-------|----------------|-------------------------| +| `cobo_id` | Populated when the transaction is created. | Remains available. | +| `request_id` | Present when your API request created the transaction; absent for deposits and other transactions without your request. | Same condition applies. | +| `token_id` | Present for Custodial Wallet, Web3 Wallet, and MPC Wallet transactions. | Remains available. | +| `asset_id` | Present only for Exchange Wallet transactions. It is mutually exclusive with `token_id` by wallet type. | Remains available. | +| `result` | Present only for `MessageSign` transactions. | Absent for every other transaction type at every stage. | +| `fee` | Not populated while signature or broadcast is pending. | Populated after broadcast. | +| `transaction_hash` | Not populated before broadcast. | Populated after broadcast. | +| `block_info` | Not populated before on-chain confirmation. | Populated after confirmation; never populated for `MessageSign`. | +| `raw_tx_info` | Not populated before assembly for broadcast. | Populated after assembly; never populated for `MessageSign`. | +| `replacement` | Not populated because no replacement can exist yet. | Populated only if an RBF operation later replaces the transaction. | + +The callback-phase example omits fields that are not yet populated: + +```json +{"message_id":"callback-001","url":"https://example.com/callback","created_timestamp":1717740300000,"data":{"data_type":"Transaction","transaction_id":"tx-callback-001","cobo_id":"202406070001","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"PendingSignature","chain_id":"ETH","token_id":"ETH_USDT","initiator_type":"API","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"created_timestamp":1717740300000,"updated_timestamp":1717740300000},"status":"Pending"} +``` + +After broadcast and confirmation, a transaction webhook can carry the later fields: + +```json +{"event_id":"event-final-001","url":"https://example.com/webhook","created_timestamp":1717740600000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-callback-001","cobo_id":"202406070001","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"Completed","chain_id":"ETH","token_id":"ETH_USDT","initiator_type":"API","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"fee":{"fee_type":"EVM_EIP_1559","token_id":"ETH","fee_used":"0.00042","estimated_fee_used":"0.0005"},"transaction_hash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","block_info":{"block_number":20123456,"block_timestamp":1717740500000,"block_hash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},"raw_tx_info":{"used_nonce":42,"raw_tx":"0x02f8..."},"confirmed_num":12,"confirming_threshold":12,"created_timestamp":1717740300000,"updated_timestamp":1717740600000},"status":"Delivered"} +``` + ### Common delivery failures The following table lists the most frequent reasons why callback messages or webhook events fail to deliver, and how to fix them. @@ -188,4 +219,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/transaction-webhook-events.mdx b/v2/guides/webhooks-callbacks/transaction-webhook-events.mdx new file mode 100644 index 00000000..bce3fd6c --- /dev/null +++ b/v2/guides/webhooks-callbacks/transaction-webhook-events.mdx @@ -0,0 +1,118 @@ +--- +title: "Transaction webhook events" +lang: "en" +description: "Understand the payload and lifecycle signals for wallets.transaction.* webhook events." +sidebarTitle: "Transaction webhook events" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +Transaction webhook events cover deposits, withdrawals, contract calls, and message signing. The four `wallets.transaction.*` events use the same webhook envelope and carry a `Transaction` object in `data`. + +## Event envelope + +| Field | Description | +|-------|-------------| +| `event_id` | The unique identifier of the webhook event. It remains the same when delivery is retried. | +| `url` | The endpoint to which Cobo delivers the event. | +| `created_timestamp` | The event creation time as a Unix timestamp in milliseconds. | +| `type` | The event type, such as `wallets.transaction.updated`. | +| `data` | The event payload. For these events, `data_type` is `Transaction`. | +| `status` | The delivery status of the event. | +| `next_retry_timestamp` | The next scheduled delivery time when `status` is `Retrying`. | +| `retries_left` | The remaining delivery attempts when `status` is `Retrying`. | + +See [Set up a callback or webhook endpoint](/v2/guides/webhooks-callbacks/set-up-endpoint) for signature verification, responses, delivery order, retries, and duplicate handling. + +## Event lifecycle + + + + + + + + + +
EventData typeWhen it occurs
wallets.transaction.createdTransactionFires once when Cobo first creates a transaction record after detecting a transaction on-chain or receiving an API request.
wallets.transaction.updatedTransactionFires whenever the status or confirmation count changes, from record creation through the terminal state.
wallets.transaction.succeededTransactionFires once when the transaction reaches its terminal successful status.
wallets.transaction.failedTransactionFires once when the transaction reaches Failed, Rejected, or Canceled. All three terminal statuses map to this event.
+ + +`wallets.transaction.created` indicates that a transaction record exists. It does not indicate that the transaction succeeded. + + +The `wallets.transaction.updated` event covers the transaction lifecycle, including creation, completion, and failure. Subscribe to this event when you need to track every status or confirmation-count change. See [Transaction statuses and sub-statuses](/v2/guides/transactions/status) to interpret `status` and `sub_status`. + +## Process updates safely + +Cobo does not guarantee that transaction events arrive in the order in which they were generated. A delivery can also be retried. Make your handler idempotent and record the `event_id`, `transaction_id`, or transaction hash values that it has processed. Reconcile an incoming event against the transaction state you already hold before applying a state transition. + +## Payload reference + +The `data` object includes `data_type: "Transaction"` together with the transaction properties. Use [Transaction fields](/v2/guides/transactions/transaction-fields) for the complete top-level field dictionary and the expanded `fee`, `block_info`, `raw_tx_info`, `replacement`, `source`, and `destination` objects. + +The following complete serialized examples cover all four events, deposits and withdrawals, EVM, UTXO, and TRON chains, and native and contract tokens. Fields that are not populated at the represented lifecycle stage are omitted. + +### Created: EVM native-token withdrawal + +```json +{ + "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f", + "url": "https://example.com/webhook", + "created_timestamp": 1717740300000, + "type": "wallets.transaction.created", + "data": { + "data_type": "Transaction", + "transaction_id": "tx-eth-created", + "cobo_id": "202406070001", + "request_id": "withdraw-eth-001", + "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "type": "Withdrawal", + "status": "PendingSignature", + "chain_id": "ETH", + "token_id": "ETH", + "source": {"source_type": "Org-Controlled", "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "address": "0x1111111111111111111111111111111111111111"}, + "destination": {"destination_type": "Address", "account_output": {"address": "0x2222222222222222222222222222222222222222", "amount": "0.5"}}, + "initiator_type": "API", + "confirmed_num": 0, + "confirming_threshold": 12, + "created_timestamp": 1717740300000, + "updated_timestamp": 1717740300000 + }, + "status": "Delivered" +} +``` + +### Updated: EVM contract-token withdrawal + +```json +{"event_id":"event-eth-updated","url":"https://example.com/webhook","created_timestamp":1717740419000,"type":"wallets.transaction.updated","data":{"data_type":"Transaction","transaction_id":"tx-eth-usdt-updated","cobo_id":"202406070002","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"Confirming","chain_id":"ETH","token_id":"ETH_USDT","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"fee":{"fee_type":"EVM_EIP_1559","token_id":"ETH","fee_used":"0.00042","estimated_fee_used":"0.0005"},"initiator_type":"API","confirmed_num":3,"confirming_threshold":12,"transaction_hash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","block_info":{"block_number":20123456,"block_timestamp":1717740400000,"block_hash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},"raw_tx_info":{"used_nonce":42,"raw_tx":"0x02f8..."},"created_timestamp":1717740300000,"updated_timestamp":1717740419000},"status":"Delivered"} +``` + +### Succeeded: UTXO native-token deposit + +```json +{"event_id":"event-btc-succeeded","url":"https://example.com/webhook","created_timestamp":1717740520000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-btc-deposit","cobo_id":"202406070003","wallet_id":"wallet-custodial-001","type":"Deposit","status":"Completed","chain_id":"BTC","token_id":"BTC","source":{"source_type":"DepositFromAddress","addresses":["bc1qsenderexample"]},"destination":{"destination_type":"DepositToAddress","wallet_id":"wallet-custodial-001","wallet_type":"Custodial","address":"bc1qcoboexample","amount":"0.015"},"initiator_type":"Blockchain","confirmed_num":6,"confirming_threshold":6,"transaction_hash":"9f86d081884c7d659a2feaa0c55ad01500000000000000000000000000000000","block_info":{"block_number":848210,"block_timestamp":1717740500000,"block_hash":"00000000000000000002example"},"raw_tx_info":{"selected_utxos":[{"tx_hash":"4a44dc15364204a80fe80e9039455cc1","vout_n":1,"token_id":"BTC","address":"bc1qsenderexample","value":"0.015"}],"raw_tx":"02000000..."},"created_timestamp":1717740000000,"updated_timestamp":1717740520000},"status":"Delivered"} +``` + +### Failed: TRON contract-token withdrawal + +```json +{"event_id":"event-tron-failed","url":"https://example.com/webhook","created_timestamp":1717740600000,"type":"wallets.transaction.failed","data":{"data_type":"Transaction","transaction_id":"tx-tron-usdt-rejected","cobo_id":"202406070004","request_id":"withdraw-tron-usdt-001","wallet_id":"wallet-mpc-002","type":"Withdrawal","status":"Rejected","failed_reason":"The transaction was rejected during approval.","chain_id":"TRON","token_id":"TRON_USDT","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-002","address":"TSourceExample111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"TDestinationExample1111111111111","amount":"250"}},"initiator_type":"Web","confirmed_num":0,"confirming_threshold":20,"created_timestamp":1717740550000,"updated_timestamp":1717740600000},"status":"Delivered"} +``` + +### Succeeded: TRON native-token deposit + +```json +{"event_id":"event-tron-succeeded","url":"https://example.com/webhook","created_timestamp":1717740720000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-tron-deposit","cobo_id":"202406070005","wallet_id":"wallet-custodial-002","type":"Deposit","status":"Completed","chain_id":"TRON","token_id":"TRON","source":{"source_type":"DepositFromAddress","addresses":["TExternalExample11111111111111111"]},"destination":{"destination_type":"DepositToAddress","wallet_id":"wallet-custodial-002","wallet_type":"Custodial","address":"TCoboExample111111111111111111111","amount":"120"},"initiator_type":"Blockchain","confirmed_num":20,"confirming_threshold":20,"transaction_hash":"8c7dd922ad47494fc02c388e12c00eac","block_info":{"block_number":62345678,"block_timestamp":1717740700000,"block_hash":"0000000003b75a4eexample"},"created_timestamp":1717740650000,"updated_timestamp":1717740720000},"status":"Delivered"} +``` + +## Related guides + +- [Transaction fields](/v2/guides/transactions/transaction-fields) +- [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) +- [Transaction statuses and sub-statuses](/v2/guides/transactions/status) +- [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type) diff --git a/v2/guides/webhooks-callbacks/webhook-event-type.mdx b/v2/guides/webhooks-callbacks/webhook-event-type.mdx index 0acafca6..026778e7 100644 --- a/v2/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2/guides/webhooks-callbacks/webhook-event-type.mdx @@ -63,6 +63,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen +See [Transaction webhook events](/v2/guides/webhooks-callbacks/transaction-webhook-events) for the shared payload, lifecycle signals, and a worked JSON example. + ### Fee Station events @@ -131,6 +133,8 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
+See [MPC TSS request webhook events](/v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events) for the shared payload, request types, statuses, and a worked JSON example. + ### Wallet and address management events @@ -152,16 +156,37 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen + + + + + + + + + + + + + + +
WalletInfo A new wallet has been created.
wallets.updatedWalletInfoA wallet has been updated.
mpc_vaults.created MPCVault A new MPC vault has been created.
mpc_vaults.updatedMPCVaultAn MPC vault has been updated.
mpc_vaults.deletedMPCVaultAn MPC vault has been deleted.
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). +### Organization events + +| Event type | Event data type | When it occurs | +|------------|-----------------|----------------| +| `organizations.updated` | `Organization` | An organization has been updated. The payload includes `org_id` and `name` to identify the organization. | + ### Token and chain management events @@ -291,10 +316,10 @@ The `compliance.kyt.screenings.status.updated` event carries a `ComplianceKytScr The case decision that drives these status changes is represented by `KytScreeningsDecisionsType`, which has the values `Approval`, `ApprovalWithAlert`, `Rejection`, and `ManualReview`. ## 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 field-level guidance, see [Transaction webhook events](/v2/guides/webhooks-callbacks/transaction-webhook-events) and [MPC TSS request webhook events](/v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events). To inspect the raw schema for any event data type, 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. Screenshot of the data property 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/transactions/transaction-fields.mdx b/v2_cn/guides/transactions/transaction-fields.mdx new file mode 100644 index 00000000..4e339d06 --- /dev/null +++ b/v2_cn/guides/transactions/transaction-fields.mdx @@ -0,0 +1,126 @@ +--- +title: "Transaction 字段" +lang: "zh-hans" +description: "查阅交易 API 操作返回并通过交易 Webhook 事件和 Callback 消息传递的 Transaction 对象。" +sidebarTitle: "Transaction 字段" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +`Transaction` 对象表示交易在整个生命周期中的信息。交易 API 操作、交易 Webhook 事件和 Callback 消息均使用此对象。 + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
字段类型说明
transaction_idstringCobo 为交易分配的唯一标识符。
cobo_idstring可用于跟踪交易的 Cobo ID。
request_idstring您为发起交易的 API 请求提供的唯一标识符。没有对应请求时（例如充币交易），该字段不存在。
wallet_idstring与交易关联的钱包唯一标识符。
typestring交易类型，例如 Deposit、Withdrawal、ContractCall 或 MessageSign。
statusstring交易在生命周期中所处的阶段。
sub_statusstringstatus 对应的更具体原因或阶段。
failed_reasonstring交易失败原因的补充详情。
chain_idstring交易所在区块链的唯一标识符。
token_idstring全托管钱包、Web3 钱包和 MPC 钱包交易中代币在 WaaS 代币目录中的标识符。
asset_idstring关联交易所账户中的资产标识符，仅适用于交易所钱包交易。
sourceobject交易来源，其结构由 source_type 决定。
destinationobject交易目标或签名输入，其结构由 destination_type 决定。
resultobjectMessageSign 交易的签名结果。其他交易类型均不包含该字段。
feeobject网络手续费详情，其结构由 fee_type 决定。该字段在广播后填充，在等待签名或广播时不存在。
initiatorstring交易发起方的名称或标识符。
initiator_typestring发起交易所使用的渠道。
confirmed_numinteger交易已获得的确认数。
confirming_thresholdintegerCobo 要求的最低确认数。
transaction_hashstring交易的链上标识符，也称为交易哈希或 txid，仅在广播后填充。
block_infoobject已确认区块的编号、时间戳和哈希。在链上确认前以及 MessageSign 交易中，该字段不存在。
raw_tx_infoobject构建后的交易数据以及 nonce 或 UTXO 详情。该字段在交易组装完成后填充，在此之前以及 MessageSign 交易中不存在。
replacementobject原交易与替代交易之间的正向或反向关联，仅在存在替代操作时出现。
categoryarray of strings您用于整理交易的自定义类别。
descriptionstring您提供的交易说明。
is_loopboolean交易是否通过 Cobo Loop 执行。
cobo_categoryarray of strings用于标识交易所关联 Cobo 工作流的系统类别。
extraarray of stringsJSON 编码的特定业务信息，每一项使用 extra_type 标识其结构。
fueling_infoobject与交易关联的 Fee Station 代付详情。
created_timestampinteger交易创建时间，采用毫秒级 Unix 时间戳。
updated_timestampinteger交易最近更新时间，采用毫秒级 Unix 时间戳。
+ +如需查看完整的 `status` 和 `sub_status` 值，请参阅[交易状态和子状态](/v2_cn/guides/transactions/status)。 + +## `token_id` 与 `asset_id` + +`token_id` 是代币在 WaaS 代币目录中的标识符，例如 `ETH`、`ETH_USDT` 或 `BTC`。调用 [List enabled tokens](/v2/api-references/wallets/list-enabled-tokens) 获取您的组织可用的标识符。 + +`token_id` 在全托管钱包、Web3 钱包和 MPC 钱包交易中填充。`asset_id` 是关联交易所账户中的资产标识符，仅在交易所钱包交易中填充。交易根据钱包类型包含其中一个字段，而不会同时包含两者。这两个字段不可互换。 + +## `request_id` + +`request_id` 仅存在于您通过 API 请求发起的交易中，例如调用交易创建操作时。您可以使用该字段将交易与原始请求关联。对于充币交易，以及 Cobo 在没有收到您对应请求的情况下创建的其他交易，该字段不存在。 + +## `replacement` 与 RBF 关联 + +`replacement` 对象用于关联替代操作涉及的交易： + +| 字段 | 说明 | +|-------|------| +| `replaced_by_type` | 对原交易执行的替代操作：`Drop`、`Resend` 或 `SpeedUp`。 | +| `replaced_by_transaction_id` | 替代当前交易的新交易的 Cobo 交易 ID。 | +| `replaced_by_transaction_hash` | 替代当前交易的新交易的链上哈希。 | +| `replaced_type` | 当前交易替代另一笔交易时使用的替代操作。 | +| `replaced_transaction_id` | 被当前交易替代的原交易的 Cobo 交易 ID。 | +| `replaced_transaction_hash` | 被当前交易替代的原交易的链上哈希。 | + +如需了解替代操作和状态变化，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 + +只有 `Drop`、`Resend` 或 `SpeedUp` 操作生成的替代交易完成广播后，`replaced_by_transaction_hash` 才会填充。请结合 `replaced_by_transaction_id` 查询该替代交易。 + +## `cobo_category` + +`cobo_category` 由 Cobo 分配，与您提供的 `category` 和 `description` 不同。例如 `AutoFueling`、`BillPayment` 和 `AutoSweep`。如需查看按用途分类的值列表，请参阅 [Cobo 定义的交易类别](/v2_cn/guides/transactions/manage-transactions#cobo-定义的交易类别)。 + +## 结构化字段和条件字段 + +### `fee` + +`fee` 在交易广播后填充。在等待签名或广播时，该字段不存在。 + +`fee_type` 根据链的手续费模型决定字段结构：`EVM_EIP_1559`、`EVM_Legacy`、`UTXO`、`Fixed`、`SOL` 或 `FIL`。手续费结构可以包含手续费代币 `token_id`、实际费用 `fee_used` 和预估费用 `estimated_fee_used`。不同链的结构还会包含 gas 价格和用量、UTXO 费率、Solana compute units 或 Filecoin gas 参数。请参阅[预估交易手续费](/v2_cn/guides/transactions/estimate-fees)了解手续费模型。 + +### `block_info` + +`block_info` 在交易广播并获得链上确认后填充。对于待处理交易和 `MessageSign` 交易，该字段不存在。 + +`block_info` 包含： + +| 字段 | 说明 | +|-------|------| +| `block_number` | 包含交易的区块编号。 | +| `block_timestamp` | 区块创建时间，采用毫秒级 Unix 时间戳。 | +| `block_hash` | 区块哈希。 | + +### `raw_tx_info` + +`raw_tx_info` 在交易完成广播前组装后填充。在此阶段之前以及 `MessageSign` 交易中，该字段不存在。 + +`raw_tx_info` 包含构建后的交易数据： + +| 字段 | 说明 | +|-------|------| +| `used_nonce` | 交易使用的 nonce。 | +| `selected_utxos` | UTXO 交易选用的输入。每一项可以包含 `tx_hash`、`vout_n`、`token_id`、`address` 和 `value`，以及适用的脚本或对象链详情。 | +| `raw_tx` | 序列化后的原始交易。 | +| `unsigned_raw_tx` | 签名前序列化的交易。 | +| `utxo_changes` | UTXO 找零输出。每一项包含 `address`、`value` 和 `token_id`。 | + +### `result` + +`result` 仅存在于 `MessageSign` 交易中。对于消息签名结果，`result_type` 为 `Signature`，`signature` 包含原始签名数据。 + +## 来源与目标 + +`source` 和 `destination` 是使用判别字段的对象。`source_type` 标识钱包或充币来源，`destination_type` 标识地址、钱包、合约调用、充币目标或消息签名格式。请参阅[交易来源与目标](/v2_cn/guides/transactions/sources-and-destinations)了解每种交易类型支持的完整字段。 diff --git a/v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx b/v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx new file mode 100644 index 00000000..2b2324cf --- /dev/null +++ b/v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx @@ -0,0 +1,94 @@ +--- +title: "MPC TSS request Webhook 事件" +lang: "zh-hans" +description: "了解 wallets.mpc.tss_request.* Webhook 事件的 Payload 和生命周期信号。" +sidebarTitle: "MPC TSS request Webhook 事件" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +`wallets.mpc.tss_request.*` Webhook 事件报告 MPC 钱包在 Cobo Portal 中执行密钥生成和 reshare 操作的生命周期。`KeyGen` 创建组织的首个 Main Group；`KeyGenFromKeyGroup` 从现有 Main Group 派生新的 Signing Group 或 Recovery Group；`Recovery` 替换 Main Group 中某位持有者的私钥分片。 + +## 事件生命周期 + + + + + + + + + +
事件数据类型发生时机
wallets.mpc.tss_request.createdTSSRequest请求创建后、任何私钥分片持有者交互前触发一次。
wallets.mpc.tss_request.updatedTSSRequest后续每次中间状态变化时触发，包括私钥分片持有者确认、密钥生成和 MPC 处理状态。
wallets.mpc.tss_request.succeededTSSRequest请求到达 Success 终态时触发一次。
wallets.mpc.tss_request.failedTSSRequest请求到达无法继续处理的失败终态时触发一次。
+ +`PendingKeyHolderConfirmation`、`KeyHolderConfirmationFailed`、`KeyGenerating` 和 `MPCProcessing` 等中间状态通过 `updated` 事件投递，而不会通过终态事件投递。初始请求状态通过 `created` 投递；最终结果通过 `succeeded` 或 `failed` 投递。 + +## Payload 参考 + +| 字段 | 类型 | 说明 | +|-------|------|------| +| `tss_request_id` | string | TSS 请求的唯一标识符。 | +| `source_key_share_holder_group` | object | 现有来源私钥分片持有者组。该字段在 `KeyGenFromKeyGroup` 和 `Recovery` 请求中填充；`KeyGen` 没有现有来源组，因此不包含该字段。 | +| `target_key_share_holder_group_id` | string | 所有请求类型的目标组：`KeyGen` 新建的 Main Group、`KeyGenFromKeyGroup` 派生的 Signing Group 或 Recovery Group，或者 `Recovery` 中成员私钥分片被替换的 Main Group。 | +| `type` | string | 请求类型：`KeyGen`、`KeyGenFromKeyGroup` 或 `Recovery`。 | +| `status` | string | TSS 请求当前所处的生命周期状态。 | +| `description` | string | TSS 请求的说明。 | +| `created_timestamp` | integer | 请求创建时间，采用毫秒级 Unix 时间戳。 | + +提供 `source_key_share_holder_group` 时，该对象包含： + +| 字段 | 类型 | 说明 | +|-------|------|------| +| `key_share_holder_group_id` | string | 来源私钥分片持有者组的标识符。 | +| `tss_node_ids` | array of strings | 参与创建新私钥分片持有者组的 TSS Node ID。 | + +以下示例涵盖四种结果。每个对象均包含对应请求中已填充的全部字段。 + +### Created + +```json +{ + "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f", + "url": "https://example.com/webhook", + "created_timestamp": 1701396866000, + "type": "wallets.mpc.tss_request.created", + "data": { + "data_type": "TSSRequest", + "tss_request_id": "20240711114129000132315000003970", + "target_key_share_holder_group_id": "fd9519ae-507b-4605-b108-04d4e5ffcdd3", + "type": "KeyGen", + "status": "PendingKeyHolderConfirmation", + "description": "Create the first Main Group", + "created_timestamp": 1701396866000 + }, + "status": "Delivered" +} +``` + +### Updated + +```json +{"event_id":"event-tss-updated","url":"https://example.com/webhook","created_timestamp":1701396966000,"type":"wallets.mpc.tss_request.updated","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"MPCProcessing","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +### Succeeded + +```json +{"event_id":"event-tss-succeeded","url":"https://example.com/webhook","created_timestamp":1701397066000,"type":"wallets.mpc.tss_request.succeeded","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"Success","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +### Failed + +```json +{"event_id":"event-tss-failed","url":"https://example.com/webhook","created_timestamp":1701397166000,"type":"wallets.mpc.tss_request.failed","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003972","target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd4","type":"KeyGen","status":"KeyGeneratingFailed","description":"Create the first Main Group","created_timestamp":1701396866000},"status":"Delivered"} +``` + +如需了解投递和重试行为，请参阅[设置 Callback 或 Webhook Endpoint](/v2_cn/guides/webhooks-callbacks/set-up-endpoint)。 + +## 相关指南 + +- [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type) diff --git a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx index ae7e44c0..fe974c6e 100644 --- a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx +++ b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx @@ -100,6 +100,37 @@ Cobo 不保证事件将按生成顺序交付。例如，创建转账将生成以 如果 Callback Endpoint 没有响应，响应状态码不是 `200` 或 `201`，或响应包体不包含 `ok` 或 `deny`，WaaS 服务将继续重试发送消息。如果重试次数达到 30 次，WaaS 服务将停止发送消息，Callback 消息状态将变为**发送失败**。您可以使用 [Retry callback message](/v2/api-references/developers/retry-callback-message) 来重新发送消息。 +### Callback 消息 Payload + +Callback 消息的 `data` 字段使用 `Transaction` 对象。该对象表示 Callback Endpoint 必须返回 `ok` 或 `deny` 时的交易状态，因此请勿将其视为最终交易状态。交易后续处理过程中产生的交易 Webhook 事件使用相同的对象。 + +请参阅 [Transaction 字段](/v2_cn/guides/transactions/transaction-fields)了解完整字段字典，包括 `cobo_id`、`request_id`、`token_id`、`asset_id`、`result`、`fee`、`transaction_hash`、`block_info`、`raw_tx_info` 和 `replacement`。处理 Callback 时，请根据该 Callback 消息中实际提供的值做出决策。如需获取交易的后续状态，请查询交易或处理后续的交易 Webhook 事件。 + +| 字段 | Callback 阶段 | 后续交易阶段 | +|------|---------------|--------------| +| `cobo_id` | 创建交易时填充。 | 后续仍然可用。 | +| `request_id` | 您的 API 请求创建交易时存在；对于充币和其他没有对应请求的交易，该字段不存在。 | 适用相同条件。 | +| `token_id` | 全托管钱包、Web3 钱包和 MPC 钱包交易中存在。 | 后续仍然可用。 | +| `asset_id` | 仅在交易所钱包交易中存在。该字段与 `token_id` 根据钱包类型互斥。 | 后续仍然可用。 | +| `result` | 仅在 `MessageSign` 交易中存在。 | 其他交易类型在任何阶段均不包含该字段。 | +| `fee` | 等待签名或广播时未填充。 | 广播后填充。 | +| `transaction_hash` | 广播前未填充。 | 广播后填充。 | +| `block_info` | 链上确认前未填充。 | 确认后填充；`MessageSign` 交易始终不包含该字段。 | +| `raw_tx_info` | 完成广播前组装之前未填充。 | 完成组装后填充；`MessageSign` 交易始终不包含该字段。 | +| `replacement` | 此时尚不可能存在替代交易，因此未填充。 | 仅当后续 RBF 操作替代该交易时填充。 | + +以下 Callback 阶段示例省略尚未填充的字段： + +```json +{"message_id":"callback-001","url":"https://example.com/callback","created_timestamp":1717740300000,"data":{"data_type":"Transaction","transaction_id":"tx-callback-001","cobo_id":"202406070001","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"PendingSignature","chain_id":"ETH","token_id":"ETH_USDT","initiator_type":"API","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"created_timestamp":1717740300000,"updated_timestamp":1717740300000},"status":"Pending"} +``` + +广播并确认后，交易 Webhook 可以携带后续字段： + +```json +{"event_id":"event-final-001","url":"https://example.com/webhook","created_timestamp":1717740600000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-callback-001","cobo_id":"202406070001","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"Completed","chain_id":"ETH","token_id":"ETH_USDT","initiator_type":"API","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"fee":{"fee_type":"EVM_EIP_1559","token_id":"ETH","fee_used":"0.00042","estimated_fee_used":"0.0005"},"transaction_hash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","block_info":{"block_number":20123456,"block_timestamp":1717740500000,"block_hash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},"raw_tx_info":{"used_nonce":42,"raw_tx":"0x02f8..."},"confirmed_num":12,"confirming_threshold":12,"created_timestamp":1717740300000,"updated_timestamp":1717740600000},"status":"Delivered"} +``` + ### 常见投递失败原因 下表列出了 Callback 消息和 Webhook 事件最常见的投递失败原因及修复方法。 @@ -175,4 +206,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/transaction-webhook-events.mdx b/v2_cn/guides/webhooks-callbacks/transaction-webhook-events.mdx new file mode 100644 index 00000000..399848af --- /dev/null +++ b/v2_cn/guides/webhooks-callbacks/transaction-webhook-events.mdx @@ -0,0 +1,118 @@ +--- +title: "Transaction Webhook 事件" +lang: "zh-hans" +description: "了解 wallets.transaction.* Webhook 事件的 Payload 和生命周期信号。" +sidebarTitle: "Transaction Webhook 事件" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +交易 Webhook 事件适用于充币、提币、合约调用和消息签名。四个 `wallets.transaction.*` 事件使用相同的 Webhook Envelope，并在 `data` 中携带 `Transaction` 对象。 + +## Event Envelope + +| 字段 | 说明 | +|-------|------| +| `event_id` | Webhook 事件的唯一标识符，重试投递时保持不变。 | +| `url` | Cobo 投递事件的 Endpoint。 | +| `created_timestamp` | 事件创建时间，采用毫秒级 Unix 时间戳。 | +| `type` | 事件类型，例如 `wallets.transaction.updated`。 | +| `data` | 事件 Payload。对于这些事件，`data_type` 为 `Transaction`。 | +| `status` | 事件的投递状态。 | +| `next_retry_timestamp` | `status` 为 `Retrying` 时的下次计划投递时间。 | +| `retries_left` | `status` 为 `Retrying` 时剩余的投递次数。 | + +如需了解签名验证、响应、投递顺序、重试和重复处理，请参阅[设置 Callback 或 Webhook Endpoint](/v2_cn/guides/webhooks-callbacks/set-up-endpoint)。 + +## 事件生命周期 + + + + + + + + + +
事件数据类型发生时机
wallets.transaction.createdTransactionCobo 在链上检测到交易或收到 API 请求并首次创建交易记录时触发一次。
wallets.transaction.updatedTransaction从创建记录到终态，只要状态或确认数发生变化就会触发。
wallets.transaction.succeededTransaction交易到达成功终态时触发一次。
wallets.transaction.failedTransaction交易到达 Failed、Rejected 或 Canceled 终态时触发一次。这三种状态均映射到该事件。
+ + +`wallets.transaction.created` 表示交易记录已存在，不表示交易已成功。 + + +`wallets.transaction.updated` 涵盖交易生命周期，包括创建、完成和失败。如果您需要跟踪每次状态或确认数变化，请订阅此事件。请参阅[交易状态和子状态](/v2_cn/guides/transactions/status)了解 `status` 和 `sub_status`。 + +## 安全处理更新 + +Cobo 不保证交易事件按照生成顺序到达。投递也可能重试。请确保处理逻辑具有幂等性，并记录已经处理的 `event_id`、`transaction_id` 或交易哈希。应用状态变化前，请将收到的事件与您已保存的交易状态进行核对。 + +## Payload 参考 + +`data` 对象包含 `data_type: "Transaction"` 以及交易属性。请参阅 [Transaction 字段](/v2_cn/guides/transactions/transaction-fields)了解完整的顶层字段字典，以及展开后的 `fee`、`block_info`、`raw_tx_info`、`replacement`、`source` 和 `destination` 对象。 + +以下完整序列化示例涵盖各事件结果、充币和提币、EVM、UTXO 和 TRON 链，以及原生代币和合约代币。未在相应生命周期阶段填充的字段不会出现。 + +### Created：EVM 原生代币提币 + +```json +{ + "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f", + "url": "https://example.com/webhook", + "created_timestamp": 1717740300000, + "type": "wallets.transaction.created", + "data": { + "data_type": "Transaction", + "transaction_id": "tx-eth-created", + "cobo_id": "202406070001", + "request_id": "withdraw-eth-001", + "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "type": "Withdrawal", + "status": "PendingSignature", + "chain_id": "ETH", + "token_id": "ETH", + "source": {"source_type": "Org-Controlled", "wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "address": "0x1111111111111111111111111111111111111111"}, + "destination": {"destination_type": "Address", "account_output": {"address": "0x2222222222222222222222222222222222222222", "amount": "0.5"}}, + "initiator_type": "API", + "confirmed_num": 0, + "confirming_threshold": 12, + "created_timestamp": 1717740300000, + "updated_timestamp": 1717740300000 + }, + "status": "Delivered" +} +``` + +### Updated：EVM 合约代币提币 + +```json +{"event_id":"event-eth-updated","url":"https://example.com/webhook","created_timestamp":1717740419000,"type":"wallets.transaction.updated","data":{"data_type":"Transaction","transaction_id":"tx-eth-usdt-updated","cobo_id":"202406070002","request_id":"withdraw-usdt-001","wallet_id":"wallet-mpc-001","type":"Withdrawal","status":"Confirming","chain_id":"ETH","token_id":"ETH_USDT","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-001","address":"0x1111111111111111111111111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"0x3333333333333333333333333333333333333333","amount":"100"}},"fee":{"fee_type":"EVM_EIP_1559","token_id":"ETH","fee_used":"0.00042","estimated_fee_used":"0.0005"},"initiator_type":"API","confirmed_num":3,"confirming_threshold":12,"transaction_hash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","block_info":{"block_number":20123456,"block_timestamp":1717740400000,"block_hash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},"raw_tx_info":{"used_nonce":42,"raw_tx":"0x02f8..."},"created_timestamp":1717740300000,"updated_timestamp":1717740419000},"status":"Delivered"} +``` + +### Succeeded：UTXO 原生代币充币 + +```json +{"event_id":"event-btc-succeeded","url":"https://example.com/webhook","created_timestamp":1717740520000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-btc-deposit","cobo_id":"202406070003","wallet_id":"wallet-custodial-001","type":"Deposit","status":"Completed","chain_id":"BTC","token_id":"BTC","source":{"source_type":"DepositFromAddress","addresses":["bc1qsenderexample"]},"destination":{"destination_type":"DepositToAddress","wallet_id":"wallet-custodial-001","wallet_type":"Custodial","address":"bc1qcoboexample","amount":"0.015"},"initiator_type":"Blockchain","confirmed_num":6,"confirming_threshold":6,"transaction_hash":"9f86d081884c7d659a2feaa0c55ad01500000000000000000000000000000000","block_info":{"block_number":848210,"block_timestamp":1717740500000,"block_hash":"00000000000000000002example"},"raw_tx_info":{"selected_utxos":[{"tx_hash":"4a44dc15364204a80fe80e9039455cc1","vout_n":1,"token_id":"BTC","address":"bc1qsenderexample","value":"0.015"}],"raw_tx":"02000000..."},"created_timestamp":1717740000000,"updated_timestamp":1717740520000},"status":"Delivered"} +``` + +### Failed：TRON 合约代币提币 + +```json +{"event_id":"event-tron-failed","url":"https://example.com/webhook","created_timestamp":1717740600000,"type":"wallets.transaction.failed","data":{"data_type":"Transaction","transaction_id":"tx-tron-usdt-rejected","cobo_id":"202406070004","request_id":"withdraw-tron-usdt-001","wallet_id":"wallet-mpc-002","type":"Withdrawal","status":"Rejected","failed_reason":"The transaction was rejected during approval.","chain_id":"TRON","token_id":"TRON_USDT","source":{"source_type":"Org-Controlled","wallet_id":"wallet-mpc-002","address":"TSourceExample111111111111111111"},"destination":{"destination_type":"Address","account_output":{"address":"TDestinationExample1111111111111","amount":"250"}},"initiator_type":"Web","confirmed_num":0,"confirming_threshold":20,"created_timestamp":1717740550000,"updated_timestamp":1717740600000},"status":"Delivered"} +``` + +### Succeeded：TRON 原生代币充币 + +```json +{"event_id":"event-tron-succeeded","url":"https://example.com/webhook","created_timestamp":1717740720000,"type":"wallets.transaction.succeeded","data":{"data_type":"Transaction","transaction_id":"tx-tron-deposit","cobo_id":"202406070005","wallet_id":"wallet-custodial-002","type":"Deposit","status":"Completed","chain_id":"TRON","token_id":"TRON","source":{"source_type":"DepositFromAddress","addresses":["TExternalExample11111111111111111"]},"destination":{"destination_type":"DepositToAddress","wallet_id":"wallet-custodial-002","wallet_type":"Custodial","address":"TCoboExample111111111111111111111","amount":"120"},"initiator_type":"Blockchain","confirmed_num":20,"confirming_threshold":20,"transaction_hash":"8c7dd922ad47494fc02c388e12c00eac","block_info":{"block_number":62345678,"block_timestamp":1717740700000,"block_hash":"0000000003b75a4eexample"},"created_timestamp":1717740650000,"updated_timestamp":1717740720000},"status":"Delivered"} +``` + +## 相关指南 + +- [Transaction 字段](/v2_cn/guides/transactions/transaction-fields) +- [交易来源与目标](/v2_cn/guides/transactions/sources-and-destinations) +- [交易状态和子状态](/v2_cn/guides/transactions/status) +- [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type) diff --git a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx index 4653ec1e..9fd85cba 100644 --- a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx @@ -64,6 +64,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; +请参阅 [Transaction Webhook 事件](/v2_cn/guides/webhooks-callbacks/transaction-webhook-events)了解共享 Payload、生命周期信号和 JSON 示例。 + ### Fee Station 相关事件 @@ -133,6 +135,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; +请参阅 [MPC TSS request Webhook 事件](/v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events)了解共享 Payload、请求类型、状态和 JSON 示例。 + ### 钱包与地址管理事件 @@ -154,16 +158,37 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + + + + + + + + + + + + +
WalletInfo 已创建新的钱包。
wallets.updatedWalletInfo钱包已更新。
mpc_vaults.created MPCVault 已创建新的 MPC Vault。
mpc_vaults.updatedMPCVaultMPC Vault 已更新。
mpc_vaults.deletedMPCVaultMPC Vault 已删除。
激活 Solana 代币子地址（Associated Token Account）不会触发 `wallets.addresses.created` 事件。为激活该地址而发生的租金转账也不会触发任何 `wallets.transaction.*` 事件，且不会生成充币或交易记录。因此，Solana 代币账户的激活及其租金无法通过 webhook 感知。详情请参阅 [Solana 代币账户租金](/v2_cn/guides/transactions/solana-token-account-rent)。 +### 组织事件 + +| 事件类型 | 事件数据类型 | 发生时机 | +|----------|--------------|----------| +| `organizations.updated` | `Organization` | 组织已更新。Payload 包含用于标识组织的 `org_id` 和 `name`。 | + ### 代币与链管理事件 @@ -293,10 +318,10 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 驱动这些状态变化的案件决策由 `KytScreeningsDecisionsType` 表示，其取值包括 `Approval`、`ApprovalWithAlert`、`Rejection` 和 `ManualReview`。 ## 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 Webhook 事件](/v2_cn/guides/webhooks-callbacks/transaction-webhook-events)和 [MPC TSS request Webhook 事件](/v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events)。如需检查任意事件数据类型的原始 Schema，请参阅 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) 属性。 Webhook 数据结构截图 您可以在事件数据类型之间切换来查看每个事件数据类型的数据结构。 -另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。 \ No newline at end of file +另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。