docs: add webhook delivery semantics, retry behavior, and self-diagnosis guide

[rcsh1]

Intent

Ticket 1178598175370948986 (提币交易状态在Submitted没有收到webhook推送): There is no transaction-status-to-webhook trigger matrix, and no documentation on delivery timing, retry behavior, or SLA expectations. Document the full status-to-webhook trigger matrix and add a delivery semantics section.'

Summary

Improve the webhook documentation to help integrators self-diagnose missing webhook notifications (Ticket: 提币交易状态在 Submitted 没有收到 webhook 推送). Six files updated (EN + CN pairs).

Changed files

• v2/guides/webhooks-callbacks/set-up-endpoint.mdx — added ##### Retry behavior and ##### Delivery guarantees subsections
• v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx — CN mirror (##### 重试行为, ##### 投递保证)
• v2/guides/webhooks-callbacks/introduction.mdx — added ## Delivery semantics section and ### No webhook received? Self-diagnosis checklist
• v2_cn/guides/webhooks-callbacks/introduction.mdx — CN mirror (## 投递机制, ### 未收到 Webhook 事件？自助排查)
• v2/guides/webhooks-callbacks/webhook-event-type.mdx — added cross-link to transaction status reference
• v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx — CN mirror cross-link

All edits restate facts already documented (2s timeout, 10 attempts, 200/201 success, ordering not guaranteed, duplicate delivery possible). No new timing, SLA, or dispatch-behavior claims were asserted.

[cobosteven]

Doc PR Review — CoboGlobal/developer-site #366

Verdict: REQUEST_CHANGES

Summary

The PR is well-scoped and bilingually faithful: every new EN section, bullet, and self-diagnosis step has a one-to-one CN counterpart, no event codes or status enums are fabricated, and code-side fact-verification surfaced 0 failures (no wrong/invented error codes, status codes, or timing claims). However, one must_fix blocks approval: self-diagnosis step 4 in introduction.mdx (EN and CN) links to a 'Common delivery failures' / '常见投递失败原因' anchor in set-up-endpoint that the PR never creates, so the remediation step resolves to nothing and is non-actionable. Per the verdict rule a must_fix standards violation forces REQUEST_CHANGES; the remaining items are should_fix/nit polish.

must_fix

1. Broken cross-link / non-actionable remediation step — introduction.mdx self-diagnosis step 4 (EN + CN).
   • EN step 4 links to /v2/guides/webhooks-callbacks/set-up-endpoint#common-delivery-failures; CN step 4 links to set-up-endpoint#常见投递失败原因.
   • The PR adds only Retry behavior/重试行为 and Delivery guarantees/投递保证 to set-up-endpoint. No "Common delivery failures"/"常见投递失败原因" heading exists in any EN or CN webhooks-callbacks file (grep-confirmed by both reviewers), so the anchor goes nowhere and "resolve the cause" degenerates into a vague directive (violates the exact-path / valid-internal-link rule).
   • Reviewer disagreement on severity (surfaced): standards reviewer rates this must_fix (broken internal link + non-actionable step); bilingual reviewer rates it should_fix (consistently broken in BOTH languages, a real defect but not an EN/CN divergence). Synthesis keeps it must_fix because actionability of the fix step is the governing standard regardless of language parity.
   • Fix (apply to both languages): either add the referenced Common delivery failures / 常见投递失败原因 section to both set-up-endpoint files, or re-point step 4 at the #retry-behavior / #重试行为 anchor that actually exists.

[rcsh1]

The only review item is a stale must-fix from cobosteven on June 22, 2026 saying the self-diagnosis step links to a missing section. But on the actual PR branch playbook/run-run_d582a0364048 / local checkout pr-
366-run_d582a0364048, both target sections already exist:

• EN: ### Common delivery failures in Documents/github/developer-site/v2/guides/webhooks-callbacks/set-up-endpoint.mdx
• CN: ### 常见投递失败原因 in Documents/github/developer-site/v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx

And the self-diagnosis links in:

• Documents/github/developer-site/v2/guides/webhooks-callbacks/introduction.mdx
• Documents/github/developer-site/v2_cn/guides/webhooks-callbacks/introduction.mdx

already point to those matching anchors.

[cobosteven]

Verdict: REQUEST_CHANGES

总评

本 PR 仅复述已有事实、未引入新的计时/SLA/分发声明；事实核查（claude + codex 两分支）0 项 failure，未发现伪造或错误的 error/status code。但仍有 4 项 must_fix 需要修复后再放行：CN 状态枚举值 Delivered/Failed 被翻译，以及自助排查清单第 1/3/4 步缺少可直接操作的 Portal 路径、产品模式层级和具体补救/重试动作。

must_fix

• 【双语一致性】v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx 的 ##### 重试行为 将事件状态枚举值翻译为「已送达」「发送失败」，但 EN 使用 Delivered / Failed。枚举值不应翻译；CN 应保持 Delivered、Failed。
• 【标准合规】v2/guides/webhooks-callbacks/introduction.mdx 及 CN 镜像的 ### No webhook received? Self-diagnosis / ### 未收到 Webhook 事件？自助排查 第 1 步只说确认 endpoint 已订阅事件类型，但未说明在哪里查看/修改订阅，也未给完整 API 动作。请补充确切 Cobo Portal 点击路径或完整 curl/API-reference 动作。
• 【标准合规】同一自助排查清单第 3 步的 Portal 路径缺少 WaaS 2.0 产品模式层级。请统一为 EN: Cobo Portal / Developer / WaaS 2.0 / Webhook Events；CN: Cobo Portal / 开发者 / WaaS 2.0 / Webhook 事件。
• 【标准合规】同一自助排查清单第 4 步的 “resolve the cause, then click Retry”（CN 镜像同义）不可直接操作。请写出常见原因的具体补救动作，并给出失败事件在点击 Retry 前的确切路径或 API 动作。

_{🤖 自动文档 PR 独立审查(doc-pr-review)。}

[rcsh1]

Addressed the current review feedback in the latest push (ad39e692):

1. Preserved the canonical delivery-status enum literals in CN: replaced the translated labels with verbatim Delivered at v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx:81 and :87, and Failed at :90.
2. Made self-diagnosis step 1 actionable in both languages at v2/guides/webhooks-callbacks/introduction.mdx:59 and v2_cn/guides/webhooks-callbacks/introduction.mdx:59: readers can use the endpoint-information API to inspect subscribed_events, then the endpoint-update API to submit the complete desired list. This matches the verified implementation: custody/waas2/webhooks/views/dev/webhook_endpoint.py:43 accepts subscribed_events, custody/waas2/webhooks/client/client.py:187 uses PUT v1/webhooks/endpoints/{endpoint_id}/, and custody/waas2/webhooks/client/client.py:190 sends the exact JSON key subscribed_events. The documented example event is also backed by custody/custody/cobo/settings/91_webhook.py:10, where wallets.transaction.updated appears verbatim as an event_type value.
3. Restored the product-mode level in step 3 at v2/guides/webhooks-callbacks/introduction.mdx:61 and v2_cn/guides/webhooks-callbacks/introduction.mdx:61: Cobo Portal > Developer > WaaS 2.0 > Webhook Events / Cobo Portal > 开发者 > WaaS 2.0 > Webhook 事件.
4. Made step 4 executable at v2/guides/webhooks-callbacks/introduction.mdx:62 and v2_cn/guides/webhooks-callbacks/introduction.mdx:62: it points to the concrete common-failure remedies, directs readers from the step-3 event list into the failed event detail page, and tells them to click Retry / 重新发送 and confirm. It also provides the retry API alternative using endpoint_id and event_id. The flow is supported by custody/waas2/webhooks/views/dev/event_retry.py:19, custody/waas2/webhooks/urls_dev.py:27, and the published operation developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/retry_by_event_id.yaml:10; Portal confirmation executes the retry at custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:171.

The June 22 broken-anchor finding was not a change required in this revision: the later issue-level comment and current branch confirm that both ### Common delivery failures and ### 常见投递失败原因 targets already exist and match the links. The empty approval and general summary text requested no changes, so no response was needed for those items.

运行过程记录（自动生成）

• 读取的评审意见与修订要点（来自 revision brief）：核对了 submitted reviews、issue-level comments 以及 inline review comments；当前需处理的四项为 CN 状态枚举、自助排查第 1/3/4 步。inline review comments 返回为空，因此没有可回复的 thread id。June 22 的 broken-anchor 意见已由后续 issue-level comment 及当前分支状态确认过时；空白 approval 与表扬/概述未提出修订要求。
• 代码核查结论与证据（repo/path:line，如有）：custody/custody/cobo/settings/91_webhook.py:10 确认 wallets.transaction.updated；custody/waas2/webhooks/views/dev/webhook_endpoint.py:43、custody/waas2/webhooks/client/client.py:187、custody/waas2/webhooks/client/client.py:190 确认 endpoint 查询/更新所用的 subscribed_events 流程；custody/waas2/webhooks/views/dev/event_retry.py:19、custody/waas2/webhooks/urls_dev.py:27、developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/retry_by_event_id.yaml:10 和 custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:171 确认重试 API 与 Portal 确认动作。
• 本次推送的改动（来自 git log -1 --stat）：commit ad39e6927ba881b0d22a7578d25eb5129daf2199（docs: address review feedback），修改 3 个文件，共 9 insertions、9 deletions：v2/guides/webhooks-callbacks/introduction.mdx、v2_cn/guides/webhooks-callbacks/introduction.mdx、v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx。
• 同步基线：a8ad72ddedd1676dad804f6fe444bce0795c76ab