docs: 完善 Webhook 事件与交易运维文档 - #387
Conversation
|
关联 product-manual PR：CoboGlobal/product-manual#755 |
运行过程记录（自动生成）本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。 1. 意图（确认后）来源：T96128（https://pha.1cobo.com/T96128）。任务汇总了 126 条 H1 Webhook/event-type 反馈，其中 112 条来自 custody，约 70% 涉及应由文档回答的 payload、字段或状态语义。本次需要调查并修复以下 10 个文档问题：
2. 探索发现（按仓库 × explorer）由于完整 findings 超出 GitHub 单条评论限制，本节按规范截断为每个 explorer 的 developer-site × explorer A现有 custody × explorer A确认 Callback 使用 custody-2.0-website × explorer APortal 要求选择 custody-2.0-website × explorer BTransaction 前端类型确认 developer-site-waas2 × explorer AOpenAPI 枚举 55 个 literal event，并通过 developer-site-waas2 × explorer BSpec 已定义 Transaction、TSSRequest、CallbackMessage、事件查询与重发接口，真正缺口主要位于 Developer Hub 指南。Transaction schema 证明 cobo-libs × explorer A共享 WebhookEvent 只保存 organization/channel、opaque cobo-libs × explorer B代理 client 确认外部 Webhook 服务提供事件筛选分页、详情、日志、订阅 conditions 和 3. 综合结论result 问题最终被归类为文档深度和信息架构不足，而不是事件注册表缺失。现有事件参考已列出 Transaction、MPC TSS 等事件族，但主要停留在单行触发说明并跳转到通用 schema；客户真正需要的是完整 payload、条件字段语义、生命周期决策和运维流程。可扩展方案是每个 payload family 一个页面，每个 literal event 一个可定位小节和代表性完整 JSON；本轮优先处理 Transaction 与 MPC TSS。 任务 1–6 和任务 9 的大部分结论已有强代码证据：Transaction Webhook 使用公开 Transaction serializer； 下游 Webhook 服务不在可访问仓库，因此没有发布新的确认 body、retry cadence/计数、A/B Endpoint 隔离或公开 retention 数值。现有数字仅作为原文保留，不宣称在本轮重新验证。公开文档仅加入已证实的 Endpoint 级查看、日志、修复后重发、幂等和 Transaction API 对账流程；历史过期时建议对账，但不承诺查询完整性。 confidence： open_questions
汇总代码证据
4. 编辑计划[
{"task_id":"transaction-payload-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/transaction-events.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/webhooks/managers/wallet_event.py:114","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364"],"code_evidence_missing":false},
{"task_id":"transaction-payload-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-events.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/webhooks/managers/wallet_event.py:114"],"code_evidence_missing":false},
{"task_id":"mpc-payload-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/mpc-tss-request-events.mdx","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:29","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:41","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:130"],"code_evidence_missing":false},
{"task_id":"mpc-payload-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/mpc-tss-request-events.mdx","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:29","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:41","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:130"],"code_evidence_missing":false},
{"task_id":"event-index-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_source_event.py:52","custody/waas2/webhooks/managers/vault_event.py:31","custody/waas2/webhooks/managers/balance_event.py:15","custody/waas2/webhooks/managers/wallet_chain_event.py:23","custody/waas2/webhooks/managers/wallet_token_event.py:35"],"code_evidence_missing":false},
{"task_id":"event-index-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_source_event.py:52","custody/waas2/webhooks/managers/vault_event.py:31","custody/waas2/webhooks/managers/balance_event.py:15","custody/waas2/webhooks/managers/wallet_chain_event.py:23","custody/waas2/webhooks/managers/wallet_token_event.py:35"],"code_evidence_missing":false},
{"task_id":"callback-fields-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/developers/managers/callback_message.py:177","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:180","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:197"],"code_evidence_missing":false},
{"task_id":"callback-fields-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/developers/managers/callback_message.py:177","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:180","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:197"],"code_evidence_missing":false},
{"task_id":"transaction-fields-en","repo_alias":"primary","doc_file":"v2/guides/transactions/transaction-fields.mdx","code_evidence":["custody/waas2/coins/managers.py:587","custody/waas2/transactions/mongo/manager/write/fields/token.py:24","custody/waas2/webhooks/managers/wallet_event.py:114","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:22"],"code_evidence_missing":false},
{"task_id":"transaction-fields-cn","repo_alias":"primary","doc_file":"v2_cn/guides/transactions/transaction-fields.mdx","code_evidence":["custody/waas2/coins/managers.py:587","custody/waas2/transactions/mongo/manager/write/fields/token.py:24","custody/waas2/webhooks/managers/wallet_event.py:114","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:22"],"code_evidence_missing":false},
{"task_id":"crediting-en","repo_alias":"primary","doc_file":"v2/guides/transactions/status.mdx","code_evidence":["custody/custody/handler/blockchain_handler.py:1186","custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},
{"task_id":"crediting-cn","repo_alias":"primary","doc_file":"v2_cn/guides/transactions/status.mdx","code_evidence":["custody/custody/handler/blockchain_handler.py:1186","custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},
{"task_id":"scenarios-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:22","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:202","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:215"],"code_evidence_missing":false},
{"task_id":"scenarios-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:22","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:202","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:215"],"code_evidence_missing":false},
{"task_id":"retry-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/developers/managers/callback_message.py:239","custody/waas2/webhooks/managers/managers.py:105","custody/waas2/webhooks/models.py:20","custody/waas2/webhooks/client/client.py:302","custody/waas2/webhooks/client/client.py:325"],"code_evidence_missing":false},
{"task_id":"retry-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/developers/managers/callback_message.py:239","custody/waas2/webhooks/managers/managers.py:105","custody/waas2/webhooks/models.py:20","custody/waas2/webhooks/client/client.py:302","custody/waas2/webhooks/client/client.py:325"],"code_evidence_missing":false},
{"task_id":"multi-endpoint-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/webhooks/client/client.py:261","custody/waas2/webhooks/client/client.py:302"],"code_evidence_missing":false},
{"task_id":"multi-endpoint-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx","code_evidence":["custody/waas2/webhooks/client/client.py:261","custody/waas2/webhooks/client/client.py:302"],"code_evidence_missing":false},
{"task_id":"recovery-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/client/client.py:261","custody/waas2/webhooks/client/client.py:302","custody/waas2/webhooks/client/client.py:325","custody/waas2/webhooks/views/event_retries.py:19"],"code_evidence_missing":false},
{"task_id":"recovery-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/client/client.py:261","custody/waas2/webhooks/client/client.py:302","custody/waas2/webhooks/client/client.py:325","custody/waas2/webhooks/views/event_retries.py:19"],"code_evidence_missing":false},
{"task_id":"portal-recovery-en","repo_alias":"alt-docs","doc_file":"snippets/webhook-events-en.mdx","code_evidence":["custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:26","custody-2.0-website/src/services/developers/index.ts:181","custody/waas2/webhooks/views/event_retries.py:19"],"code_evidence_missing":false},
{"task_id":"portal-recovery-cn","repo_alias":"alt-docs","doc_file":"snippets/webhook-events-cn.mdx","code_evidence":["custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:26","custody-2.0-website/src/services/developers/index.ts:181","custody/waas2/webhooks/views/event_retries.py:19"],"code_evidence_missing":false},
{"task_id":"retention-en","repo_alias":"primary","doc_file":"v2/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event.py:153","custody/waas2/webhooks/models.py:20"],"code_evidence_missing":false},
{"task_id":"retention-cn","repo_alias":"primary","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-operations.mdx","code_evidence":["custody/waas2/webhooks/managers/wallet_event.py:153","custody/waas2/webhooks/models.py:20"],"code_evidence_missing":false},
{"task_id":"portal-retention-en","repo_alias":"alt-docs","doc_file":"snippets/webhook-events-en.mdx","code_evidence":[],"code_evidence_missing":true},
{"task_id":"portal-retention-cn","repo_alias":"alt-docs","doc_file":"snippets/webhook-events-cn.mdx","code_evidence":[],"code_evidence_missing":true},
{"task_id":"navigation","repo_alias":"primary","doc_file":"docs.json","code_evidence":[],"code_evidence_missing":true}
]5. 评审轮次第 1 轮：未通过Reviewer 指出 Transaction 完整 payload 表未把 第 2 轮：未通过Reviewer 验证上述结构化字段、八组 Transaction 示例、四组 MPC 示例、字段修正、中文 anchor 和 legacy anchor 均已正确实现；未发现内部路径引用、未确认标记或被翻译的标识符。唯一遗漏是 最终修正在 6. 基线与同步
|
2 participants
关联来源
意图
本次变更针对 T96128 汇总的高频 Webhook、Callback 与交易字段问题，补齐 Transaction 和 MPC TSS request 事件的完整结构、触发语义与示例。文档同时明确交易入账判断、字段对账方式、投递与重试边界，并提供按场景订阅和失败恢复流程。所有公开结论均以现有代码证据为边界，未确认的下游重试隔离和保留时长不作为事实发布。
变更摘要
docs.json：在中英文导航中注册新增的事件、运维和交易字段页面，确保页面可发现。v2/guides/transactions/status.mdx：明确区块链充值的入账条件以及Confirming、Completed、wallets.transaction.succeeded的关系。v2/guides/transactions/transaction-fields.mdx：新增交易字段对账字典，说明标识符、方向、RBF 和cobo_category的用途与条件。v2/guides/webhooks-callbacks/mpc-tss-request-events.mdx：新增 MPC TSS request 事件结构、触发条件和完整示例。v2/guides/webhooks-callbacks/set-up-endpoint.mdx：区分 Webhook 与 Callback 投递规则，补充 Callback 字段可空性、多 Endpoint 排查和幂等处理。v2/guides/webhooks-callbacks/transaction-events.mdx：新增 Transaction 事件结构、四类事件触发语义和跨链示例。v2/guides/webhooks-callbacks/webhook-event-type.mdx：将事件表改为索引并补充已确认的事件类型与新页面链接。v2/guides/webhooks-callbacks/webhook-operations.mdx：新增场景订阅矩阵、失败恢复流程、WEBHOOK RESEND权限前提和历史过期后的对账建议。v2_cn/guides/transactions/status.mdx：同步区块链充值入账条件和状态关系。v2_cn/guides/transactions/transaction-fields.mdx：同步交易字段对账字典并保留字段和枚举标识符。v2_cn/guides/webhooks-callbacks/mpc-tss-request-events.mdx：同步 MPC TSS request 事件结构、条件和示例。v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx：同步投递规则、字段可空性、多 Endpoint 排查和幂等处理。v2_cn/guides/webhooks-callbacks/transaction-events.mdx：同步 Transaction 事件结构、触发语义和跨链示例。v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx：同步事件索引、已确认事件类型和新页面链接。v2_cn/guides/webhooks-callbacks/webhook-operations.mdx：同步场景订阅、失败恢复、WEBHOOK RESEND权限前提和历史过期对账流程。需要在其他仓库改动
product-manual/snippets/webhook-events-en.mdx与product-manual/snippets/webhook-events-cn.mdx不在本工作区；需要在product-manual仓库补充 PortalRetry权限、投递日志排查及历史过期后的 Developer Hub 对账链接。代码证据
custody/waas2/webhooks/managers/wallet_event_by_source.py:25：证明Success产生wallets.transaction.succeeded，Failed、Rejected和Canceled产生wallets.transaction.failed。custody/waas2/webhooks/managers/wallet_event_by_source.py:51：证明 Transaction Webhook 使用公开 Transaction 详情序列化结果。custody/waas2/webhooks/managers/wallet_event_by_source.py:116：证明created有条件触发、updated始终尝试触发，终态事件会额外触发。custody/waas2/webhooks/managers/wallet_event.py:114：证明充值和退款方向为Inbound，其他交易类型为Outbound。custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21：证明 MPC TSS 事件前缀为wallets.mpc.tss_request。custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:29：证明 MPC TSS Webhook 适用于 Portal 密钥生成和重分享请求。custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:41：证明请求状态决定created、updated、succeeded和failed事件。custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:130：证明公开 MPC 字段及条件性source_group的序列化方式。custody/waas2/developers/managers/callback_message.py:177：证明 Callback 的data使用当前公开 Transaction 结构。custody/waas2/developers/managers/callback_message.py:239：证明 Callback 确认要求 HTTP 200/201 和准确的ok/deny响应体。custody/waas2/transactions/dev/bo/transaction_query/transaction.py:364：证明 Transaction 字段及cobo_id、asset_id、result、replacement、cobo_category的可空性。custody/waas2/coins/managers.py:587：证明token_id、chain_id和asset_id的公开映射来源。custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:22：证明AutoSweep等cobo_category的具体分类。custody/custody/handler/blockchain_handler.py:1186：证明confirmed_number >= confirming_threshold后才进入链上已确认转换。custody/waas2/transactions/dev/enums/transaction.py:220：证明内部Success映射为公开Completed。custody/waas2/webhooks/client/client.py:261：证明事件列表支持 Endpoint、状态、类型、方向筛选和游标分页。custody/waas2/webhooks/client/client.py:302：证明投递日志按 Endpoint 和事件查询并支持游标分页。custody/waas2/webhooks/client/client.py:325：证明下游服务提供事件重试接口。custody/waas2/webhooks/views/event_retries.py:19：证明公开重发需要WEBHOOK RESEND权限和组织范围。custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:202：证明 Portal 注册 Endpoint 时必须选择订阅事件。custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:215：证明 Portal 注册 Endpoint 时必须选择钱包范围。custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:26：证明 Portal 手动重发受权限控制。docs.json的导航注册没有运行时代码证据，已通过mintlify validate验证页面和导航构建。product-manual仓库未包含在本工作区，尚未修改snippets/webhook-events-en.mdx和snippets/webhook-events-cn.mdx；需要在该仓库核实并补充 Portal 恢复流程和历史过期说明。