Callback request and response formats

Try 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, the node will periodically send the request to verify server availability.

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 operation.
vault	`object`	The vault information. For details, see the response of the 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 operation.
tss_request	`object`	The TSS request information. For details, see the response of the 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 operation.
vault	`object`	The vault information. For details, see the response of the Get vault information operation.
wallet	`object`	The wallet information. For details, see the response of the 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 operation.
source_addresses	`array[object]`	The information of the source addresses of the transaction. For details, see the response of the List wallet addresses operation.
transaction	`object`	The information of the transaction to sign. For details, see the response of the 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 operation.

TypeKeyReshare request

Used for key resharing 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 operation.
vault	`object`	The vault information. For details, see the response of the 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 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 operation.
tss_request	`object`	The TSS request information. For details, see the response of the 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

// Callback request (TypeKeySign) from the TSS Node
{
  "request_id": "f1e2d3c4b5a6",
  "request_type": 2,
  "request_detail": "{...}",
  "extra_info": "{...}"
}

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

Overview

Get started

Webhooks and callbacks

Transactions

MPC Wallets

Resources

Callback request and response formats

Callback request

Base request structure

TypePing request

TypeKeyGen request

request_detail

extra_info

TypeKeySign request

request_detail

extra_info

TypeKeyReshare request

request_detail

extra_info

Callback response

HTTP response requirements

Example

Important notes

​Callback request

​Base request structure

​TypePing request

​TypeKeyGen request

​request_detail

​extra_info

​TypeKeySign request

​request_detail

​extra_info

​TypeKeyReshare request

​request_detail

​extra_info

​Callback response

​HTTP response requirements

​Example

​Important notes

Callback request

Base request structure

TypePing request

TypeKeyGen request

request_detail

extra_info

TypeKeySign request

request_detail

extra_info

TypeKeyReshare request

request_detail

extra_info

Callback response

HTTP response requirements

Example

Important notes