> ## Documentation Index > Fetch the complete documentation index at: https://cobo.com/developers/llms.txt > Use this file to discover all available pages before exploring further. # Callback request and response formats > Detailed specifications of the payload formats used in TSS Node callback server interaction Try [Cobo WaaS Skill](/developers/v2/guides/overview/cobo-waas-skill) in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀 This document specifies the request and response payload formats used in TSS Node callback server communication. ## Callback request The callback request is sent from the TSS Node to the callback server. ### Base request structure | Field | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | request\_id | `string` | The unique ID of the callback request. | | request\_type | `int` | Type of the callback request:
- `TypePing` (0): Used for heartbeat monitoring
- `TypeKeyGen` (1): Creating new key shares for your MPC Wallets.
- `TypeKeySign` (2): Signing transactions or messages.
- `TypeKeyReshare` (3): Redistributing key shares among participants. | | request\_detail | `string` | Details specific to the request type. The structure varies depending on the request type. The content is a JSON-serialized string. | | extra\_info | `string` | Additional contextual information. The structure varies depending on the request type. The content is a JSON-serialized string. | ### TypePing request Used for heartbeat monitoring of the callback server. If you have specified the `monitor_interval` parameter when [configuring the TSS Node settings](/developers/v2/guides/mpc-wallets/server-co-signer/callback-server-configure#configure-tss-node-settings), the node will periodically send the request to verify server availability. ```yaml theme={null} callback: monitor_interval: 1h # Monitoring interval; if empty, monitoring is disabled ``` For `TypePing` requests, `request_id`, `request_detail` and `extra_info` will be empty objects. ### TypeKeyGen request Used for key share generation. #### request\_detail | Field | Type | Description | | ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- | | threshold | `int` | The number of key share holders required to approve operations in this key share holder group. | | node\_ids | `array[string]` | The TSS Node IDs of the key share holders in this key share holder group. | | curve | `int` | The elliptic curve type of the root extended public key. Possible values:
`0`: Secp256k1
`2`: Ed25519. | | task\_id | `string` | The unique identifier for this key generation task. | | biz\_task\_id | `string` | For this request type, this field contains the TSS request ID. | #### extra\_info | Field | Type | Description | | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. | | project | `object` | The project information. For details, see the response of the [Get project information](/developers/v2/api-references/wallets--mpc-wallets/get-project-information) operation. | | vault | `object` | The vault information. For details, see the response of the [Get vault information](/developers/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. | | target\_key\_share\_holder\_group | `object` | The key share holder group information. For details, see the response of the [Get key share holder group information](/developers/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. | | tss\_request | `object` | The TSS request information. For details, see the response of the [Get TSS request](/developers/v2/api-references/wallets--mpc-wallets/get-tss-request) operation. | ### TypeKeySign request Used for transaction or message signing operations. #### request\_detail | Field | Type | Description | | ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | group\_id | `string` | The ID of the TSS key share group. | | root\_pub\_key | `string` | The root extended public key of the group. | | used\_node\_ids | `array[string]` | The list of TSS Node IDs participating in signing. | | bip32\_path\_list | `array[string]` | The BIP32 derivation paths. | | msg\_hash\_list | `array[string]` | The list of message hashes to sign. | | tweak\_list | `array[string]` | The list of tweaks to apply. | | signature\_type | `int` | The type of signature to generate. Possible values:
- `1`: ECDSA signature
- `2`: EdDSA signature
- `3`: Schnorr signature | | tss\_protocol | `int` | The TSS protocol. Possible values:
- `1`: GG18
- `2`: Lindell
- `3`: EddsaTSS | | task\_id | `string` | The unique identifier for this signing task. | | biz\_task\_id | `string` | For this request type, this field contains the transaction ID. | #### extra\_info | Field | Type | Description | | --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. | | project | `object` | The project information. For details, see the response of the [Get project information](/developers/v2/api-references/wallets--mpc-wallets/get-project-information) operation. | | vault | `object` | The vault information. For details, see the response of the [Get vault information](/developers/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. | | wallet | `object` | The wallet information. For details, see the response of the [Get wallet information](/developers/v2/api-references/wallets/get-wallet-information) operation. | | signer\_key\_share\_holder\_group | `object` | The information of the key share holder group that signs the transaction. For details, see the response of the [Get key share holder group information](/developers/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. | | source\_addresses | `array[object]` | The information of the source addresses of the transaction. For details, see the response of the [List wallet addresses](/developers/v2/api-references/wallets/list-wallet-addresses) operation. | | transaction | `object` | The information of the transaction to sign. For details, see the response of the [Get transaction information](/developers/v2/api-references/transactions/get-transaction-information) operation. | The `transaction` object includes an `initiator_type` field that identifies how the transaction was initiated, so your callback server can distinguish, for example, an API-initiated transaction from an App-initiated one. Possible values are `API` (initiated through the WaaS API), `Web` (initiated from Cobo Portal), `App` (initiated from Cobo Portal Apps), and `External` (initiated outside Cobo). For the full transaction schema, see the response of the [Get transaction information](/developers/v2/api-references/transactions/get-transaction-information) operation. ### TypeKeyReshare request Used for [key resharing](https://manuals.cobo.com/en/portal/mpc-wallets/ocw/manage-key-share-groups#manage-recovery-groups) operations. Resharing means to use an existing key share holder group to generate key shares for a new group. #### request\_detail | Field | Type | Description | | --------------- | --------------- | ------------------------------------------------------------------------------------------------ | | old\_group\_id | `string` | The ID of the existing TSS key share group. | | root\_pub\_key | `string` | The root extended public key of the vault. | | curve | `int` | The elliptic curve type of the root extended public key.
`0`: Secp256k1
`2`: Ed25519. | | used\_node\_ids | `array[string]` | The TSS Node IDs of the existing key share holder group. | | old\_threshold | `int` | The threshold value of the existing key share holder group used. | | new\_threshold | `int` | The threshold value of the new key share holder group. | | new\_node\_ids | `array[string]` | The TSS Node IDs of the new key share holder group. | | task\_id | `string` | The unique identifier for this resharing task. | | biz\_task\_id | `string` | For this request type, this field contains the TSS request ID. | #### extra\_info | Field | Type | Description | | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | org | `object` | The organization information:
- `org_id`: String. The ID of the organization.
- `name`: String. The organization name.
- `created_timestamp`: Int. The organization's creation time in Unix timestamp format, measured in milliseconds. | | project | `object` | The project information. For details, see the response of the [Get project information](/developers/v2/api-references/wallets--mpc-wallets/get-project-information) operation. | | vault | `object` | The vault information. For details, see the response of the [Get vault information](/developers/v2/api-references/wallets--mpc-wallets/get-vault-information) operation. | | source\_key\_share\_holder\_group | `object` | The information of the existing key share holder group. For details, see the response of the [Get key share holder group information](/developers/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. | | target\_key\_share\_holder\_group | `object` | The information of the new key share holder group. For details, see the response of the [Get key share holder group information](/developers/v2/api-references/wallets--mpc-wallets/get-key-share-holder-group-information) operation. | | tss\_request | `object` | The TSS request information. For details, see the response of the [Get TSS request](/developers/v2/api-references/wallets--mpc-wallets/get-tss-request) operation. | ## Callback response Your callback server must respond to all callback requests with the following structure: | Field | Type | Description | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | status | `int` | The response status code. `0` indicates success. Any other value indicates that an error occurred while processing the request in the callback server. | | request\_id | `string` | The unique ID of the callback request. | | action | `string` | Action to take. Possible values:
- `APPROVE`: Approve the request and proceed with the operation
- `REJECT`: Deny the request and stop the operation | | error | `string` | The error message:
- When `status` is not `0`: Contains internal error messages from the callback server.
- When `status` is `0` and action is `REJECT`: Contains the specific reason for the rejection. | ### HTTP response requirements The callback response described above is the JSON body of the HTTP response. Return your response with an HTTP `200` (OK) status code, and set the body `status` field to `0` to indicate that your callback server processed the callback successfully. The HTTP status code and the body `status` field are different. The HTTP status code reports whether the HTTP request reached and was handled by your callback server, while the body `status` field reports the result of processing the callback: a value of `0` indicates success, and any other value indicates that an error occurred in the callback server while processing the request. #### Example ```json theme={null} // Callback request (TypeKeySign) from the TSS Node { "request_id": "f1e2d3c4b5a6", "request_type": 2, "request_detail": "{...}", "extra_info": "{...}" } ``` ```json theme={null} // Callback response (HTTP status code 200) { "status": 0, "request_id": "f1e2d3c4b5a6", "action": "APPROVE", "error": "" } ``` ### Important notes * If the TSS Node fails to receive an HTTP response, it will retry the callback request. * After exceeding the maximum retry attempts, the risk control result will be set to `REJECT`. * For `TypePing` requests, a successful response (body `status` `0`) indicates that your callback server is available.