如何使用 Toden 可靠地获取结果
Charles Archibong, 联合创始人
使用已签名的 Webhook 接收器可靠地接收 Toden 结果。验证确切的字节，持久存储每个事件，并在不重复客户操作的情况下恢复重试。
要点
- 篡改过的签名和过期的签名均不予接受。
- 一次逻辑重发会触发一项业务操作。
- 接收器恢复功能在进程重启后仍然存在。
- 延迟事件无法覆盖较新的状态。
- 轮换机制会在整个宽限期内有效运作。
收到 Toden 使用已签名的 Webhook 接收器可以可靠地获取结果。验证确切的字节，持久存储每个事件，并在不重复客户操作的情况下恢复重试。
开始之前
用于验证签名的服务器端点
持久的重复数据处理和重试恢复
授权 API 服务器结果检索密钥
请使用具有此控制权限的团队成员。更改设置前，请检查组织和环境。付款或持续注册前，请审核当前价格。屏幕截图显示的是示例工作区或公共集成参考；它们不显示真实客户或已完成的付款。
设置并使用该功能
步骤 1：准备后端接收器
创建公共 HTTPS 具有有效证书且无重定向的端点。它必须先收到完整的原始请求体。 JSON 中间件改变了这一切。要规划一个持久的收件箱，以逻辑事件 ID 为键，并针对慢速任务进行后台处理。接收方应该位于后端；浏览器回调并不能替代可靠的结果交付。
集成参考：验证算法
步骤 2：创建环境的 Webhook 端点
在沙盒环境中，打开“开发者”→“Webhooks”→“添加端点” 。输入端点名称 。URL 选择支持的正文版本，并选择您的集成处理的事件系列。选择“创建端点” ，并将显示的端点签名密钥保存到后端密钥存储中。请将其与您的其他数据分开存放。 API 关键在于，沙箱和生产环境需要符合环境要求的端点和密钥。
集成参考：推荐的测试顺序
步骤 3：解析前验证 V2 签名
读 X-Myaza-Signature-V2 解析已签名的时间戳和 v1 候选时间戳，拒绝无效或过期的时间戳并进行验证 HMAC - SHA256 使用时间戳、句点和原始字节。使用端点密钥和恒定时间比较。轮换期间，接受来自活动密钥或未过期宽限密钥的有效签名。使用文档中记录的方法。 SDK 或者提供接收者示例，而不是编造的签名格式。
集成参考：签名标头
步骤 4：在确认之前持久化逻辑事件
签名验证后，解析 JSON并将其信封ID 存储在持久唯一约束下。使用该 ID（而非 deliveryId）对重复业务工作进行去重。重发或兼容性别名可以承载相同的逻辑事件，但使用不同的投递方式。仅在持久接受后才返回 2xx；将慢速工作单独排队。快速返回的 2xx 邮件如果没有持久记录，则在崩溃后可能会丢失结果。
集成参考：幂等性断言
步骤五：核对当前产品结果
请使用已记录的客户、验证、交易或活动参考信息作为事件系列的标识。验证时，状态和检查状态应保持不同。事件到达顺序可能不一致，因此在进行敏感更改之前，请先获取当前资源状态或使用其受支持的版本。未知的可选字段和事件类型不应导致接收器崩溃。仅发送通知并不代表已获得资金释放权限。
集成参考：排序断言
步骤 6：测试投篮、回放和轮换
打开端点的测试操作，并发送一个受支持的模拟事件。检查传递历史记录和接收方的持久记录。重新发送该事件，并验证业务操作是否发生过一次。测试非 2xx 响应、超时后的恢复、被篡改的正文以及过期的签名。利用宽限期进行轮换，并在停用旧的接收方密钥之前测试两个签名。
集成参考：推荐的测试顺序
充分发挥这种能力
订阅产品所需的规范事件族，而不是订阅每个没有处理程序的目录条目。
如果邮件多次投递失败或出现死信，请及时通知您的团队，并保持与当前资源的核对路径。
请将确切的决策依据和解释与您的操作一起保存，以便支持人员能够证明应用程序执行的操作。
先测试再依赖它
运行此产品支持的沙箱或模拟器场景。如果某个工具仅供生产环境使用，请先检查访问权限和范围，然后仅使用经过审核的、获得许可的生产环境测试。文档截图或页面加载成功并不等同于端到端集成测试。
篡改过的签名和过期的签名均不予接受。
一次逻辑重发会触发一项业务操作。
接收器恢复功能在进程重启后仍然存在。
延迟事件无法覆盖较新的状态。
轮换机制会在整个宽限期内有效运作。
故障排除
解析后签名失败 JSON
解析前请验证原始字节。重新序列化 JSON 更改已签名的输入。
重发两次
使用逻辑事件 ID 作为持久唯一键，而不是 deliveryId。
交付显示成功，但账户未发生变化。
检查已排队的业务处理和关联情况。 HTTP 交付情况并不能证明下游副作用的存在。
打开设置和集成参考
返回解决方案 （在新标签页中打开）。选择要激活的功能，然后按照其相应的指南进行操作。
参考来源
