diff --git a/v2/guides/webhooks-callbacks/introduction.mdx b/v2/guides/webhooks-callbacks/introduction.mdx
index 056db567..e4f35832 100644
--- a/v2/guides/webhooks-callbacks/introduction.mdx
+++ b/v2/guides/webhooks-callbacks/introduction.mdx
@@ -15,13 +15,22 @@ Webhooks and callbacks are essential mechanisms for the WaaS service to communic
Callbacks and webhooks serve distinct purposes within your business operations.
-| Mechanism | Description | Trigger Condition | Required Actions Upon Receiving the Message |
-| ------------- | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| Callbacks | Serve similarly to a 2FA verification. You must register a callback endpoint in order to approve and complete a token withdrawal. | Triggered when you initiate a withdrawal or contract call using the WaaS API. | Check if the transaction meets expectations, and respond with a success status code (`200` or `201`) and a response body of `ok` or `deny` to indicate transaction approval or rejection. |
-| Webhooks | Serve as real-time notifications for events such as transaction status updates. | Triggered when certain events occur such as transaction status or TSS request status changes, based on the event types to which you subscribe. | Respond with a success status code (`200` or `201`). |
+| Mechanism | Description | Trigger Condition | Required Actions Upon Receiving the Message | Direction | Required |
+| --- | --- | --- | --- | --- | --- |
+| Callbacks | Serve similarly to a 2FA verification. You must register a callback endpoint in order to approve and complete a token withdrawal. | Triggered when you initiate a withdrawal or contract call using the WaaS API. | Check if the transaction meets expectations, and respond with a success status code (`200` or `201`) and a response body of `ok` or `deny` to indicate transaction approval or rejection. | Cobo WaaS service pushes to your server endpoint. Triggered by your own API call to initiate the operation. | Yes — you must register a callback endpoint to approve and complete token withdrawals and contract calls. Your server must respond with `ok` or `deny`. |
+| Webhooks | Serve as real-time notifications for events such as transaction status updates. | Triggered when certain events occur such as transaction status or TSS request status changes, based on the event types to which you subscribe. | Respond with a success status code (`200` or `201`). | Cobo WaaS service pushes to your server endpoint. Triggered by a subscribed platform event. | No — subscribe only to the event types you need. |
You can view the data of all webhook events and callback messages in your organization on **Cobo Portal** > **Developer**> **Webhook Events** / **Callback Messages**.
+
+The terms *webhook endpoint URL*, *callback endpoint URL*, and *TSS callback URL* refer to three distinct concepts:
+- **Webhook endpoint URL**: the URL you register in Cobo Portal under **Developer** > **WaaS 2.0** > **Webhooks**. The Cobo WaaS service pushes event notifications to this URL.
+- **Callback endpoint URL**: the URL you link to an API key under **Developer** > **WaaS 2.0** > **API Keys**. The Cobo WaaS service pushes withdrawal and contract-call approval requests to this URL.
+- **TSS callback URL**: the `service_address` field under `callback.cb_server_v2` in `cobo-tss-node-config.yaml`. This URL is called by the TSS Node software itself, not the WaaS service, before each MPC signing operation. It is configured in the TSS Node YAML file, not in Cobo Portal.
+
+If you are using MPC Wallets with a server co-signer, see [TSS Node callback mechanism](/v2/guides/mpc-wallets/server-co-signer/callback-server-overview) for details on the TSS callback URL.
+
+
## Handle webhook events and callback messages
Follow the steps listed below to handle webhook events and callback messages sent from the WaaS service:
@@ -35,6 +44,9 @@ Follow the steps listed below to handle webhook events and callback messages sen
- Respond to the API request.
- Add other handling logic (if applicable).
3. Register the endpoint on Cobo Portal.
+
+ For a webhook endpoint, in Cobo Portal, go to **Developer** > **WaaS 2.0** > **Webhooks**, then click **Register Webhook Endpoint**. For a callback endpoint, in Cobo Portal, go to **Developer** > **WaaS 2.0** > **API Keys**, create or edit an API key, and add a callback URL in the configuration modal.
+
When registering a webhook endpoint, you need to specify the event types to which you want to subscribe.
To create an endpoint and implement the handling logic, see [Set up a callback or webhook endpoint](/v2/guides/webhooks-callbacks/set-up-endpoint).
@@ -67,4 +79,4 @@ When upgrading to WaaS 2.0, you need to do the following:
The WaaS 1.0 API callbacks use a different signature algorithm compared to the WaaS 2.0 webhooks and callbacks. Do not directly register your WaaS 1.0 endpoint on Cobo Portal. Otherwise, your endpoint will receive errors due to the differences in the signature algorithm and webhook/callback data structure between WaaS 1.0 and WaaS 2.0. Ensure you refer to the [sample code](/v2/guides/webhooks-callbacks/set-up-endpoint#code-samples) provided to correctly configure your endpoint for WaaS 2.0.
-If you configure WaaS 1.0 API callbacks for transaction notifications but do not set up WaaS 2.0 webhooks, your endpoint will still receive transaction notifications from WaaS 1.0.
If you configure both WaaS 1.0 API callbacks for transaction notifications and WaaS 2.0 webhooks, while continuing to use the WaaS 1.0 API, your endpoint will receive:- From WaaS 1.0: Transaction notifications.
- From WaaS 2.0: Webhook events.
In this case, you need to implement deduplication using a unique ID (such as `cobo_id`) to avoid processing duplicate notifications.
\ No newline at end of file
+If you configure WaaS 1.0 API callbacks for transaction notifications but do not set up WaaS 2.0 webhooks, your endpoint will still receive transaction notifications from WaaS 1.0.
If you configure both WaaS 1.0 API callbacks for transaction notifications and WaaS 2.0 webhooks, while continuing to use the WaaS 1.0 API, your endpoint will receive:- From WaaS 1.0: Transaction notifications.
- From WaaS 2.0: Webhook events.
In this case, you need to implement deduplication using a unique ID (such as `cobo_id`) to avoid processing duplicate notifications.
diff --git a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
index 4153a322..3e0f2229 100644
--- a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -183,9 +183,24 @@ async def handle_webhook(
logger.info(event.data)
```
+## Verify your endpoint setup
+
+### Webhook endpoint
+
+1. Trigger a test event using the [Trigger test webhook event](/v2/api-references/developers--webhooks/trigger-test-webhook-event) API or the Cobo CLI command `cobo webhook trigger`. The test event is sent to all registered webhook endpoints and currently supports Transaction and TSSRequest event data types.
+2. In Cobo Portal, go to **Developer** > **WaaS 2.0** > **Webhook Events** and confirm the test event status shows **Delivered**.
+3. Click the event and open **Delivery logs** to inspect the HTTP response status code and body returned by your endpoint.
+4. If the status shows **Retrying** or **Failed**, see [Common delivery failures](#common-delivery-failures).
+
+### Callback endpoint
+
+1. In Cobo Portal, go to **Developer** > **WaaS 2.0** > **API Keys**, create or edit an API key, add your callback URL, and click **Test Connection** to verify the endpoint is reachable. The test returns the HTTP status code, response body, and request latency.
+2. Initiate a token withdrawal or contract call via the WaaS API to trigger a real callback message.
+3. In Cobo Portal, go to **Developer** > **WaaS 2.0** > **Callback Messages** and confirm the message status shows **Delivered** with a response body of `ok` or `deny`.
+
## ⚠️⚠️⚠️Important notes
- 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_cn/guides/webhooks-callbacks/introduction.mdx b/v2_cn/guides/webhooks-callbacks/introduction.mdx
index 763a1240..9e95640c 100644
--- a/v2_cn/guides/webhooks-callbacks/introduction.mdx
+++ b/v2_cn/guides/webhooks-callbacks/introduction.mdx
@@ -15,13 +15,22 @@ Webhook 和 Callback 是 WaaS 服务与您的 App 进行通信的重要机制。
Callback 和 webhook 在您的业务操作中具有不同的用途。
-| 机制 | 描述 | 触发条件 | 接收到消息后需要采取的操作 |
-| ------------- | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| Callback | 类似于 2FA 验证。您必须注册一个 Callback Endpoint才能批准并完成代币提币。 | 当您使用 WaaS API 发起提币或合约调用时触发。 | 检查交易是否符合预期,并以成功状态码(`200` 或 `201`)和响应体 `ok` 或 `deny` 响应,以指示交易批准或拒绝。 |
-| Webhook | 用作事件的实时通知,例如交易状态更新。 | 当某些事件发生时触发,例如交易状态或 TSS 请求状态更改,基于您订阅的事件类型。 | 以成功状态码(`200` 或 `201`)响应。 |
+| 机制 | 描述 | 触发条件 | 接收到消息后需要采取的操作 | 方向 | 是否必须 |
+| --- | --- | --- | --- | --- | --- |
+| Callback | 类似于 2FA 验证。您必须注册一个 Callback Endpoint 才能批准并完成代币提币。 | 当您使用 WaaS API 发起提币或合约调用时触发。 | 检查交易是否符合预期,并以成功状态码(`200` 或 `201`)和响应体 `ok` 或 `deny` 响应,以指示交易批准或拒绝。 | Cobo WaaS 服务向您的服务器 Endpoint 推送消息,由您调用 API 发起操作时触发。 | 是——您必须注册 Callback Endpoint 才能批准并完成代币提币和合约调用。您的服务器必须以 `ok` 或 `deny` 响应。 |
+| Webhook | 用作事件的实时通知,例如交易状态更新。 | 当某些事件发生时触发,例如交易状态或 TSS 请求状态更改,基于您订阅的事件类型。 | 以成功状态码(`200` 或 `201`)响应。 | Cobo WaaS 服务向您的服务器 Endpoint 推送消息,由订阅的平台事件触发。 | 否——仅订阅您需要的事件类型即可。 |
您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** / **Callback消息** 中查看您团队中所有 webhook 事件和Callback消息的数据。
+
+Webhook Endpoint URL、Callback Endpoint URL 和 TSS Callback URL 是三个不同的概念:
+- **Webhook Endpoint URL**:在 Cobo Portal 的**开发者** > **WaaS 2.0** > **Webhooks** 中注册的 URL。Cobo WaaS 服务将事件通知推送到此 URL。
+- **Callback Endpoint URL**:在**开发者** > **WaaS 2.0** > **API Keys** 中与 API Key 关联的 URL。Cobo WaaS 服务将提币和合约调用的审批请求推送到此 URL。
+- **TSS Callback URL**:`cobo-tss-node-config.yaml` 中 `callback.cb_server_v2` 下的 `service_address` 字段。该 URL 由 TSS Node 软件本身(而非 WaaS 服务)在执行 MPC 签名操作前调用,在 TSS Node YAML 配置文件中设置,不在 Cobo Portal 中配置。
+
+如果您使用带有服务器联署人的 MPC 钱包,请参阅 [TSS Node Callback 机制](/v2_cn/guides/mpc-wallets/server-co-signer/callback-server-overview)。
+
+
## 处理 webhook 事件和Callback消息
按照以下步骤处理 WaaS 服务发送的 webhook 事件和Callback消息:
@@ -34,7 +43,10 @@ Callback 和 webhook 在您的业务操作中具有不同的用途。
- 验证签名。
- 响应 API 请求。
- 添加其他处理逻辑(如果适用)。
-3. 在 Cobo Portal 上注册Endpoint。
+3. 在 Cobo Portal 上注册 Endpoint。
+
+ Webhook Endpoint:在 Cobo Portal 中,前往 **开发者** > **WaaS 2.0** > **Webhooks**,然后点击**注册 Webhook Endpoint**。Callback Endpoint:在 Cobo Portal 中,前往 **开发者** > **WaaS 2.0** > **API Keys**,创建或编辑 API Key,在配置弹窗中添加 Callback URL。
+
注册 Webhook Endpoint 时,您需要指定要订阅的事件类型。
要创建Endpoint并实现处理逻辑,请参阅 [设置Callback或 Webhook Endpoint](/v2_cn/guides/webhooks-callbacks/set-up-endpoint)。
@@ -68,4 +80,4 @@ WaaS 1.0 服务使用 API Callback进行交易通知和提币确认,类似于
WaaS 1.0 API Callback使用的签名算法与 WaaS 2.0 webhook 和Callback不同。请勿直接在 Cobo Portal 上注册您的 WaaS 1.0 Endpoint。否则,由于 WaaS 1.0 和 WaaS 2.0 之间的签名算法和 webhook/Callback数据结构的差异,您的Endpoint将收到错误。请确保参考提供的 [示例代码](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#code-samples) 正确配置您的 WaaS 2.0 Endpoint。
-如果您为交易通知配置了 WaaS 1.0 API Callback,但没有设置 WaaS 2.0 webhook,您的Endpoint仍将收到来自 WaaS 1.0 的交易通知。
如果您同时为交易通知配置了 WaaS 1.0 API Callback和 WaaS 2.0 webhook,并继续使用 WaaS 1.0 API,您的Endpoint将收到:- 来自 WaaS 1.0 的交易通知。
- 来自 WaaS 2.0 的 webhook 事件。
在这种情况下,您需要使用唯一 ID(例如 `cobo_id`)实现去重,以避免处理重复通知。
\ No newline at end of file
+如果您为交易通知配置了 WaaS 1.0 API Callback,但没有设置 WaaS 2.0 webhook,您的Endpoint仍将收到来自 WaaS 1.0 的交易通知。
如果您同时为交易通知配置了 WaaS 1.0 API Callback和 WaaS 2.0 webhook,并继续使用 WaaS 1.0 API,您的Endpoint将收到:- 来自 WaaS 1.0 的交易通知。
- 来自 WaaS 2.0 的 webhook 事件。
在这种情况下,您需要使用唯一 ID(例如 `cobo_id`)实现去重,以避免处理重复通知。
diff --git a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
index ae7e44c0..edfc1628 100644
--- a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -171,8 +171,23 @@ async def handle_webhook(
logger.info(event.data)
```
+## 验证您的 Endpoint 配置
+
+### Webhook Endpoint
+
+1. 使用[触发测试 Webhook 事件](/v2_cn/api-references/developers--webhooks/trigger-test-webhook-event) API 或 Cobo CLI 命令 `cobo webhook trigger` 触发测试事件。测试事件将发送至所有已注册的 Webhook Endpoint,当前支持 Transaction 和 TSSRequest 事件数据类型。
+2. 在 Cobo Portal 中前往 **开发者** > **WaaS 2.0** > **Webhook 事件**,确认测试事件状态显示为**已送达**。
+3. 点击该事件并打开**投递日志**,查看您的 Endpoint 返回的 HTTP 响应状态码和响应体。
+4. 若状态显示**重试中**或**发送失败**,请参阅[常见投递失败原因](#常见投递失败原因)。
+
+### Callback Endpoint
+
+1. 在 Cobo Portal 中前往 **开发者** > **WaaS 2.0** > **API Keys**,创建或编辑 API Key,添加 Callback URL 后点击 **Test Connection** 验证 Endpoint 是否可达。该测试返回 HTTP 状态码、响应体和请求延迟。
+2. 通过 WaaS API 发起代币提币或合约调用以触发实际 Callback 消息。
+3. 在 Cobo Portal 中前往 **开发者** > **WaaS 2.0** > **Callback 消息**,确认消息状态显示为**已送达**,响应体为 `ok` 或 `deny`。
+
## ⚠️⚠️⚠️ 注意事项
- 在接收 Webhook 事件时,您的 Endpoint 应该首先快速返回正确的状态码,然后异步处理任何后续处理,以防止超时。
- 由于 Webhook 事件存在重试机制,Webhook Endpoint 有时会多次接收到相同的事件。为了防止重复事件处理,请记录已处理的 Event ID,Transaction Hash 或 Transaction ID,并避免处理已记录的事件。
-
\ No newline at end of file
+