docs: 补充交易 webhook 载荷示例、字段字典与订阅场景指南 - #381
Conversation
运行过程记录（自动生成）本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。 1. 意图（确认后）Custody/WaaS 2.0 webhook 与 callback 交易类文档存在 7 项内容缺口，均从 FAQ 分析中定位（issue 验收标准（源自需求）：全部 7 项完成后，H2 复测应观察到本 issue 在 Mintlify 上的重复提问率下降，以及 TG/工单相关咨询量相较 H1 下降。 2. 探索发现（按仓库 × explorer）本节按顶层探索分支（对应仓库）组织，每个分支下有 2 个并行 explorer，仅保留其 handoff_brief（含 code_evidence 指向），完整 findings 正文因篇幅过长已省略——如需详情请查阅运行产物 分支 b1 — 仓库
分支 b2 — 仓库
分支 b3 — 仓库
分支 b4 — 仓库
3. 综合结论结论（result，节选）：统一结论——全部 7 项缺口均指向本 docs 仓库的同三个 prose 页面（ 置信度（confidence）：0.78 开放问题（open_questions）：
汇总代码证据清单：见下方"4. 编辑计划"中每个任务的 4. 编辑计划[
{"task_id":"payload-ref-en-page","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"payload-ref-cn-page","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"payload-ref-crosslink-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"payload-ref-crosslink-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"payload-ref-nav","action":"fix_docs","doc_file":"docs.json","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"callback-null-fields-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"callback-null-fields-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"field-dictionary-en-page","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/transaction-field-dictionary.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"field-dictionary-cn-page","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-field-dictionary.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"field-dictionary-nav","action":"fix_docs","doc_file":"docs.json","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"succeeded-creditable-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"succeeded-creditable-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"subscription-scenarios-en-page","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/subscription-scenarios.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"subscription-scenarios-cn-page","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/subscription-scenarios.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"subscription-scenarios-nav","action":"fix_docs","doc_file":"docs.json","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"retry-retention-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"retry-retention-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx","repo_alias":"primary","code_evidence_missing":false},
{"task_id":"retry-count-reconciliation","action":"skip","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","repo_alias":"primary","code_evidence_missing":true,"skip_reason":"文档称重试 10 次，一份工单称 5 次。custody 与 cobo-libs 均确认（附代码引用）二者只将事件批次提交一次给外部 WEBHOOK_SERVICE_HOST 微服务，真实的客户端点 HTTP 重试次数/退避策略/是否按端点独立均在该外部服务代码中，不在本轮可探索仓库范围内。按写作规则，未核实的说法不得写入文档，因此未修改该数字，需人工在该外部服务仓库核实。"},
{"task_id":"changelog-max-fee-amount-en","action":"fix_docs","doc_file":"v2/guides/overview/changelog.mdx","repo_alias":"primary","code_evidence_missing":true,"note":"需先从 developer-site-waas2/custody 提交历史确定正确版本号与上线日期，不得编造日期；本轮未完成，git 状态显示 changelog.mdx 未被改动。"},
{"task_id":"changelog-max-fee-amount-cn","action":"fix_docs","doc_file":"v2_cn/guides/overview/changelog.mdx","repo_alias":"primary","code_evidence_missing":true,"note":"同上，本轮未完成。"}
]（每个任务完整的 5. 评审轮次第 1 轮 — REJECTED：审查发现上一轮要求的修复未落地。 第 2 轮 — APPROVED：两个被标记的缺陷均已修复并核实—— 6. 基线与同步
|
|
原始反馈里面有要求按事件类型逐个建页（覆盖 wallets.mpc.* 等全部事件族）， 但现在 ： Transaction events ← 这次唯一做了的Fee Station events ← 没做MPC TSS request events ← 没做（wallets.mpc.tss_request.*）Wallet and address management events ← 没做Token and chain management events ← 没做Balance update events ← 没做Compliance events ← 没做也就是说 7 大事件族里只做了 1 个，其余 6 个都没有 payload/字段说明页。需要补上 |
|
Thanks for the review. Responding to both comments here since neither was posted as an inline file/line thread. Comment #1 (auto-generated run process log, 2026-07-19T10:32:58Z): no action needed — this was the doc-writing agent's own internal log of 2 review rounds that were already resolved ( Comment #2 (must-fix, 2026-07-19T10:48:51Z) — "only 1 of 7 event families has payload/field docs, need the other 6": addressed in this push (commit
Not addressed in this push (out of scope for this reviewer thread, called out separately in the revision's own notes): a non-blocking CN cross-link anchor concern and a balance-update wording polish item, both flagged as optional/deferrable — worth a quick manual spot-check in a rendered preview before merge. 运行过程记录（自动生成）
|
cobosteven
left a comment
cobosteven
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES
总评
本 PR 的代码证据整体高度可靠：claude 与 codex 对 custody / cobo-libs 中所抽样的 webhook 载荷、字段可空性、事件类型字符串、枚举值集、触发路径、7 天保留期与"仅 succeeded 可安全入账"规则均逐条复核确认，未发现任何被编造或错误的 error code，重试次数矛盾也被正确地留待人工确认。阻塞项来自标准合规维度的 2 处 must_fix：token-chain-field-dictionary.mdx 的 Token scope events 与 webhook-event-type.mdx（含 CN 镜像）的 ComplianceDisposition 事件均以 Cobo 内部工具/服务链路（CustodyCoinManager、Aladdin、DispositionFundsWebhookApi、ScreeningWebhookProcessor 等）而非开发者可观测/可操作视角撰写，违反 developer-perspective / no-internal-notes。
must_fix
v2/guides/webhooks-callbacks/token-chain-field-dictionary.mdx> Token scope events（wallet.token.enabled/wallet.token.disabled）：以 Cobo 内部 admin 工具与源码调用方（CustodyCoinManager、Aladdin、内部 WaaS 工具）解释事件，而非开发者可观测/可操作的机制。违反 developer-perspective / no-internal-notes。修复：改写为开发者视角——说明该事件在何种开发者可见操作后触发、载荷含哪些字段、订阅方应如何响应，删除内部服务/调用方名称。v2/guides/webhooks-callbacks/webhook-event-type.mdx（及v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx镜像）>ComplianceDisposition事件数据：通过内部接收转发服务（DispositionFundsWebhookApi、ScreeningWebhookController、ScreeningWebhookProcessor、ScreeningAppClientProxy）解释事件，而非开发者能观察或处理的内容。违反 developer-perspective / no-internal-notes。修复：改写为"开发者收到该事件时能看到什么、应据此做什么"，移除内部服务链路描述；中英文同步修改。
|
已在最新推送
本轮没有 inline file/line review thread，因此没有可用的 inline comment 运行过程记录（自动生成）
|
| | Event type | Trigger | | ||
| |------------|---------| | ||
| | `wallets.mpc.tss_request.created` | The request is newly created or enters the new-request status (`custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:42-47`). | | ||
| | `wallets.mpc.tss_request.succeeded` | The request status becomes `Success` (`custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:50-57`). | |
There was a problem hiding this comment.
you should never put internal codebase's file directory in the official docs.
There was a problem hiding this comment.
Addressed in the latest push (6fc4ead) — removed internal codebase file/directory citations from the anchored TSS field dictionary while preserving the public schema, enum, and event-trigger guidance (v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx:12, v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx:22, v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx:35, v2/guides/webhooks-callbacks/tss-request-field-dictionary.mdx:41). Applied the same cleanup to the CN mirror (v2_cn/guides/webhooks-callbacks/tss-request-field-dictionary.mdx:12) and swept all other webhook documentation pages modified by this PR, rewriting implementation-facing prose where needed. The sweep covered 20 EN/CN files and removed all remaining custody/... and dev_openapi.yaml: citations from those guide trees.
cobosteven
left a comment
cobosteven
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES
本 PR 为交易 webhook 载荷/字段字典/订阅场景类纯文档新增与修改。错误码、主要枚举值集合与关键行为性论断整体已核实通过，未发现错误码类捏造；但仍有 3 项 must_fix，需要修改后再合入。
【must_fix】
-
balance.frozen字段与示例值存疑：v2/guides/webhooks-callbacks/balance-update-field-dictionary.mdx的balance.frozen行，以及balance-update-webhook-payload-examples.mdx的"frozen": "5.00"（含 CN 镜像）。公开cobo_waas2SDKBalance模型只有total/available/pending/locked，无frozen；custody 内部虽有frozen默认值'0'，但当前事件构造路径只填充 4 个字段。面向公开文档应以公开 schema 为准。请删除frozen行与示例值；若产品确认会公开该字段，也最多标注为始终为'0'，不要给非零示例。 -
v2/guides/webhooks-callbacks/set-up-endpoint.mdx新增第 88 行 Portal 补投路径不完整且与本页自相矛盾：正文写 Cobo Portal > Developer > Webhook Events，但同页重试路径为 Developer > WaaS 2.0 > Webhook Events。v2_cn镜像同样需要修复。请统一为准确、完整的点击路径。 -
set-up-endpoint.mdx新增第 88 行 API 补投说明只列 [List webhook event logs] 与 [Retry webhook event by ID]，但未说明必需参数，包括重试所需的 event ID、检索遗漏日志所需的过滤/范围。v2_cn镜像同样需要补齐操作名 + 必需参数。
2 participants
关联来源
意图
Custody/WaaS 2.0 的 webhook 与 callback 交易类文档存在 7 项内容缺口，均从 FAQ 分析（issue
webhook-event-types-payload；H1 反馈 126 条，custody 相关 112 条，pain 值 61.0，webhook 模块排名第一）中定位，并通过 3 个 Aladdin 工单交叉验证。本次新增交易 webhook 载荷示例、字段字典、按场景订阅指南三个页面，并在既有页面中补充 callback 阶段字段为空的说明、succeeded才可安全用于入账的规则、以及事件保留期限说明。其中"10 次 vs 5 次"重试次数矛盾、以及 changelog 中max_fee_amount字段的回填条目，因缺乏足够代码证据未在本轮改动，留待人工确认。变更摘要
v2/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx（新增）：新增交易 webhook 完整 JSON 载荷示例参考页，覆盖 deposit/withdrawal 方向、EVM/UTXO/TRON 手续费与 raw_tx_info 差异、原生币与 token 场景。v2_cn/guides/webhooks-callbacks/transaction-webhook-payload-examples.mdx（新增）：上述页面的中文镜像，字段/事件/枚举名保持英文原文。v2/guides/webhooks-callbacks/transaction-field-dictionary.mdx（新增）：新增交易字段字典页，澄清token_id与asset_id（后者仅适用于 Exchange Wallet）、request_id可空性、replacement.replaced_by_transaction_hash（RBF）等易混淆字段。v2_cn/guides/webhooks-callbacks/transaction-field-dictionary.mdx（新增）：上述页面中文镜像。v2/guides/webhooks-callbacks/subscription-scenarios.mdx（新增）：新增按场景订阅指南，含入账最小订阅集合、提现状态跟踪映射表、订阅按端点但归属组织级 channel 的说明，以及 webhook+API 对账模式。v2_cn/guides/webhooks-callbacks/subscription-scenarios.mdx（新增）：上述页面中文镜像。v2/guides/webhooks-callbacks/webhook-event-type.mdx（修改）：新增 callback 阶段字段可能为空的说明、succeeded才可安全触发入账的规则，并链接新增的载荷示例/字段字典页面。v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx（修改）：上述改动的中文镜像。v2/guides/webhooks-callbacks/set-up-endpoint.mdx（修改）：补充 webhook 事件数据 7 天保留期限说明，未改动既有的"最多重试 10 次"表述（该项存疑，见下方待确认事项）。v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx（修改）：上述改动的中文镜像。docs.json（修改）：在中英文 webhooks-callbacks 导航分组中注册上述 3 个新页面。代码证据
custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178,470,503,598,620,669— 证明 source/destination/fee/raw_tx_info 按钱包来源（CustodialAsset/CustodialWeb3/MPC/Exchange/Deposit）分支组装，支撑载荷示例页的方向性/链类型示例。custody/waas2/transactions/dev/bo/transaction_query/fee.py:8,17,31,43— Fixed/EIP1559/Legacy/UTXO 四类手续费 DTO，支撑 EVM/UTXO 手续费示例差异。developer-site-waas2/.../transaction_destination.yaml:1-16、source_type.yaml:1-16— destination_type 15 路 oneOf 与 source_type 枚举，证明载荷按交易类型确有形状差异。custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364-396— 证明asset_id/cobo_id/request_id/result/confirmed_num/confirming_threshold/cobo_category均为 Optional，支撑字段字典与 callback 空字段说明。custody/waas2/transactions/mongo/manager/read/waas_transaction.py:335、custody/waas2/transactions/dev/bo/transaction_query/transaction.py:320-326—replaced_by_transaction_hash来自 RBF/重发关系，支撑字段字典中 RBF 字段说明。developer-site-waas2/.../transaction.yaml:45-52—token_id示例ETH_USDT搭配仅 Exchange Wallet 适用的asset_id示例USDT，是导致客户误读的原始来源，支撑字段字典的澄清内容。custody/waas2/webhooks/managers/wallet_event.py:90-109—get_transaction_data()直接对查询 API 的TransactionData对象调用to_dict()作为 webhook 事件数据，证明 webhook 与查询 API 共享 schema。custody/waas2/developers/managers/callback_message.py:164-204,556-558— callback 在提现请求阶段（广播/确认之前）即通过旧版TransactionQueryManager生成body=tx.to_json()，解释 callback 阶段字段为空的原因。custody/waas2/webhooks/managers/wallet_event_by_source.py:26-31,139-152—wallets.transaction.succeeded仅在状态变为 Success 时触发，而updated无条件触发，支撑"仅 succeeded 可安全入账"规则。custody/waas2/webhooks/managers/wallet_event.py:145-171—delete_old_webhook_events()每小时清理 7 天前的 webhook 事件记录，支撑事件保留期限说明。custody/waas2/webhooks/controller/webhook_endpoint.py:27,65、cobo-libs/cobo_libs/webhook/client/client.py:126-137、cobo-libs/cobo_libs/webhook/utils/channel_id_resolver.py:9— 证明订阅按端点（subscribed_events）配置但channel_id对应组织级 Portal org_id，支撑订阅场景指南中"按端点订阅、组织级 channel"的说明。set-up-endpoint.mdx中"webhook 最多重试 10 次"的既有表述与一份客户工单描述的"1 秒内重试 5 次后停止"存在矛盾。已检索custody/waas2/webhooks/managers/managers.py:105、custody/waas2/webhooks/client/client.py:206、custody/waas2/webhooks/services/webhook_service.py:225-233、cobo-libs/cobo_libs/webhook/data/enums.py:4-6，确认 custody 与 cobo-libs 仅将事件批次提交一次给外部WEBHOOK_SERVICE_HOST微服务，实际面向客户端点的 HTTP 重试次数/退避策略/是否端点间独立，均在该外部服务代码中，未在本轮可探索仓库范围内，因此本次未修改该数字，需要人工在该外部服务仓库中核实后再更新。max_fee_amount新增 changelog 条目，格式参照changelog.mdx:436的estimated_fee_used条目）本轮未完成——需要先从developer-site-waas2/custody的提交历史中确定该字段实际上线的版本号与日期，避免编造日期，因此本 PR 暂不包含该改动，需人工补充。wallet_id/amount）已通过在载荷示例页对应数组处添加说明性 Note 的方式安全规避，不阻塞本次合并，如后续可访问developer-site-waas2schema 仓库可再行核实。