From e90d7916fbf8bba54dd96433507c53fd5eb88211 Mon Sep 17 00:00:00 2001
From: rcsh <163504257+rcsh1@users.noreply.github.com>
Date: Thu, 18 Jun 2026 11:04:54 +0800
Subject: [PATCH] docs: add webhook delivery semantics, retry behavior, and
 self-diagnosis guide

---
 v2/guides/webhooks-callbacks/introduction.mdx    | 15 +++++++++++++++
 v2/guides/webhooks-callbacks/set-up-endpoint.mdx | 16 ++++++++++------
 .../webhooks-callbacks/webhook-event-type.mdx    |  2 ++
 v2_cn/guides/webhooks-callbacks/introduction.mdx | 16 ++++++++++++++++
 .../webhooks-callbacks/set-up-endpoint.mdx       | 16 ++++++++++------
 .../webhooks-callbacks/webhook-event-type.mdx    |  1 +
 6 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/v2/guides/webhooks-callbacks/introduction.mdx b/v2/guides/webhooks-callbacks/introduction.mdx
index 056db567..7412f3ba 100644
--- a/v2/guides/webhooks-callbacks/introduction.mdx
+++ b/v2/guides/webhooks-callbacks/introduction.mdx
@@ -45,6 +45,21 @@ To learn more about event types and event data types, see [Webhook event type an
 
 To manage webhook events using Cobo CLI, refer to the following guides: [Listen and Forward Events](/v2/developer-tools/cobo-cli/listen-and-forward-events), [Trigger Webhook Events](/v2/developer-tools/cobo-cli/trigger-events), and [List Event Types](/v2/developer-tools/cobo-cli/event-types).
 
+## Delivery semantics
+
+Review the following rules so you can tell whether a missing notification is expected behavior or a problem to investigate.
+
+- **Event triggers.** A transaction emits webhook events as its status changes. To track the full lifecycle of a transaction with a single subscription, subscribe to `wallets.transaction.updated`, which covers creation, updates, completion, and failure. For the full list of events, see [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+- **Ordering and retries.** Event ordering is not guaranteed, and the same event may be delivered more than once, so deduplicate by a unique identifier. Failed deliveries are retried automatically. See [Retry behavior](/v2/guides/webhooks-callbacks/set-up-endpoint#retry-behavior) and [Delivery guarantees](/v2/guides/webhooks-callbacks/set-up-endpoint#delivery-guarantees).
+
+### No webhook received? Self-diagnosis
+
+If your endpoint does not receive an expected webhook event, work through the following checklist:
+
+1. Confirm that your endpoint subscribes to the relevant event type, in particular `wallets.transaction.updated` for transaction status changes.
+2. Confirm that the event you expect is one the WaaS service emits, using [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
+3. Inspect the delivery logs on **Cobo Portal** > **Developer** > **Webhook Events**, then click the event to view each delivery attempt, its response code, and its response body.
+4. If the event status is `Failed`, resolve the cause (see [Common delivery failures](/v2/guides/webhooks-callbacks/set-up-endpoint#common-delivery-failures)), then click **Retry** to resend the event.
 
 ## Notes on upgrading from WaaS 1.0 to Waas 2.0
 
diff --git a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
index 05944a50..b5232761 100644
--- a/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -80,15 +80,19 @@ Properly responding to webhook events and callback messages is crucial for ensur
 
 When your webhook endpoint receives a webhook event, it should respond with a status code of `200` or `201` to indicate that the event has been successfully received and processed. Once this response is sent, the WaaS service will stop retrying to send the event and the event status will become `Delivered` on Cobo Portal.
 
-The default timeout for each webhook event is 2 seconds. If the webhook endpoint does not respond or responds with a status code other than `200` or `201`, the WaaS service will continue to retry sending the event. If the number of retry attempts reaches 10 , the WaaS service will stop sending the event and the event status will become `Failed`· You can resend the event by clicking **Retry** on **Cobo Portal** > **Developer** > **WaaS 2.0** > **Webhook Events**.
+##### Retry behavior
 
-Cobo does not guarantee that events will be delivered in the order they are generated. For example, creating a transfer will generate the following events:
+The default timeout for each webhook event is 2 seconds. The WaaS service evaluates your endpoint's response as follows:
 
-- `wallets.transaction.created`
-- `wallets.transaction.updated`
-- `wallets.transaction.succeeded`
+- A status code of `200` or `201` is treated as success. The event status becomes `Delivered` and no further delivery attempts are made.
+- Any other status code, an invalid response, or no response within the timeout is treated as a retryable failure, and the WaaS service retries delivery.
 
-Your endpoint should not assume that events will arrive in this sequence and must handle delivery appropriately.
+The WaaS service attempts delivery up to 10 times. After the 10th failed attempt, the WaaS service stops sending the event and the event status becomes `Failed`. You can resend a failed event by clicking **Retry** on **Cobo Portal** > **Developer** > **WaaS 2.0** > **Webhook Events**.
+
+##### Delivery guarantees
+
+- **Ordering is not guaranteed.** The WaaS service does not guarantee that events are delivered in the order they are generated. For example, creating a transfer generates `wallets.transaction.created`, `wallets.transaction.updated`, and `wallets.transaction.succeeded`; your endpoint must not assume the events arrive in that sequence.
+- **Duplicate delivery is possible.** Because events are retried, your endpoint may receive the same event more than once. Deduplicate using a unique identifier such as the event ID, transaction hash, or transaction ID, and ignore events you have already processed.
 
 #### Callback messages
 
diff --git a/v2/guides/webhooks-callbacks/webhook-event-type.mdx b/v2/guides/webhooks-callbacks/webhook-event-type.mdx
index 324358a3..cb4015e5 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
   </tbody>
 </table>
 
+To see the full list of statuses a transaction passes through, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status).
+
 ### Fee Station events
 
 <table class="table-three-cols">
diff --git a/v2_cn/guides/webhooks-callbacks/introduction.mdx b/v2_cn/guides/webhooks-callbacks/introduction.mdx
index 763a1240..202568db 100644
--- a/v2_cn/guides/webhooks-callbacks/introduction.mdx
+++ b/v2_cn/guides/webhooks-callbacks/introduction.mdx
@@ -45,6 +45,22 @@ Callback 和 webhook 在您的业务操作中具有不同的用途。
 
 要使用 Cobo CLI 管理 webhook 事件，请参阅以下指南：[监听和转发事件](/v2_cn/developer-tools/cobo-cli/listen-and-forward-events)、[触发 webhook 事件](/v2_cn/developer-tools/cobo-cli/trigger-events) 和 [列出事件类型](/v2_cn/developer-tools/cobo-cli/event-types)。
 
+## 投递机制
+
+请阅读以下规则，以便判断未收到通知是预期行为还是需要排查的问题。
+
+- **事件触发。** 交易会随着其状态变化发出 webhook 事件。如需通过单个订阅跟踪交易的完整生命周期，请订阅 `wallets.transaction.updated`，它涵盖创建、更新、完成和失败。有关完整的事件列表，请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。
+- **顺序与重试。** 事件顺序不保证，且同一事件可能被多次投递，因此请使用唯一标识符进行去重。失败的投递会自动重试。请参阅 [重试行为](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#重试行为) 和 [投递保证](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#投递保证)。
+
+### 未收到 Webhook 事件？自助排查
+
+如果您的 Endpoint 未收到预期的 webhook 事件，请按照以下清单逐项排查：
+
+1. 确认您的 Endpoint 已订阅相关的事件类型，特别是用于交易状态变化的 `wallets.transaction.updated`。
+2. 使用 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type) 确认您期望的事件是 WaaS 服务会发出的事件。
+3. 在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看投递日志，然后单击该事件以查看每次投递尝试、其响应码和响应包体。
+4. 如果事件状态为 `Failed`，请解决原因（参阅 [常见投递失败原因](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#常见投递失败原因)），然后单击 **重新发送** 来重新发送事件。
+
 ## 从 WaaS 1.0 升级到 WaaS 2.0 的注意事项
 
 WaaS 1.0 服务使用 API Callback进行交易通知和提币确认，类似于 WaaS 2.0 中引入的 webhook 和Callback。以下表格提供了两种版本基于事件通知机制的比较：
diff --git a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
index 10d4f67c..2ce8b848 100644
--- a/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
+++ b/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx
@@ -80,15 +80,19 @@ Webhook 事件和 Callback 消息对于确保 WaaS 服务与您的 App 之间的
 
 当您的 Webhook Endpoint 收到 Webhook 事件时，它应该响应状态码 `200` 或 `201` 以指示事件已成功接收和处理。一旦发送此响应，WaaS 服务将停止重试发送事件，事件状态将变为**已送达**。
 
-默认情况下，每个 Webhook 事件的超时时间为 2 秒。如果 Webhook Endpoint 没有响应或响应状态码不是 `200` 或 `201`，WaaS 服务将继续重试发送事件。如果重试次数达到 10 次，WaaS 服务将停止发送事件，事件状态将变为**发送失败**。您可以通过单击 Cobo Portal > 开发者 > WaaS 2.0 > Webhook 事件上的**重新发送**来重新发送事件。
+##### 重试行为
 
-Cobo 不保证事件将按生成顺序交付。例如，创建转账将生成以下事件：
+默认情况下，每个 Webhook 事件的超时时间为 2 秒。WaaS 服务按如下方式评估您 Endpoint 的响应：
 
-- `wallets.transaction.created`
-- `wallets.transaction.updated`
-- `wallets.transaction.succeeded`
+- 状态码 `200` 或 `201` 被视为成功。事件状态变为 **已送达**，不再进行后续投递尝试。
+- 其他任何状态码、无效响应或在超时时间内无响应，均被视为可重试的失败，WaaS 服务将重试投递。
 
-您的 Endpoint 不应假设事件将按此顺序到达。
+WaaS 服务最多尝试投递 10 次。在第 10 次投递失败后，WaaS 服务将停止发送事件，事件状态变为 **发送失败**。您可以单击 **Cobo Portal** > **开发者** > **WaaS 2.0** > **Webhook 事件** 上的 **重新发送** 来重新发送失败的事件。
+
+##### 投递保证
+
+- **不保证投递顺序。** WaaS 服务不保证事件按生成顺序投递。例如，创建转账会生成 `wallets.transaction.created`、`wallets.transaction.updated` 和 `wallets.transaction.succeeded`；您的 Endpoint 不应假设事件将按此顺序到达。
+- **可能重复投递。** 由于事件会被重试，您的 Endpoint 可能会多次收到同一事件。请使用唯一标识符（例如 Event ID、Transaction Hash 或 Transaction ID）进行去重，并忽略已处理的事件。
 
 #### Callback 消息
 
diff --git a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
index 23d2d4d6..15771c77 100644
--- a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
+++ b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx
@@ -64,6 +64,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
   </tbody>
 </table>
 
+要查看交易经历的完整状态列表，请参阅 [交易状态和子状态](/v2_cn/guides/transactions/status)。
 
 ### Fee Station 相关事件