Webhook 重试与幂等基础

Webhook 是业务通知，不是重复执行操作的授权。接收端必须先验证真实性、识别已经处理的事件，并且只有在完成安全记录后才返回文档要求的确认结果。

使用公网 HTTPS 地址

配置可从公网访问、专用于 Webhook 的 HTTPS URL。不要使用内网地址、多重跳转或要求交互式登录的页面。

处理“Webhook 重试与幂等基础”时，应把“使用公网 HTTPS 地址”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

处理前先验证签名

使用当前 Webhook Secret 和文档规定的签名字段进行验证。无法验证的请求必须失败关闭，不能改变订单、余额或账户状态。

处理“Webhook 重试与幂等基础”时，应把“处理前先验证签名”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

保存幂等事件身份

在执行副作用前持久化稳定事件或业务身份。重复投递应返回已有处理结果，不能再次创建同一业务动作。

处理“Webhook 重试与幂等基础”时，应把“保存幂等事件身份”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

精确返回 SUCCESS

只有 HTTP 2xx 且响应正文去除首尾空白后严格等于 SUCCESS，才会被 MangoOTP 视为成功确认。其他正文、非 2xx 和传输失败都不是确认。

处理“Webhook 重试与幂等基础”时，应把“精确返回 SUCCESS”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

理解有限重试时间

未确认事件会在 1、3、5、15 分钟后继续投递，最多共五次通知。接收端容量和告警应覆盖这组明确上限。

处理“Webhook 重试与幂等基础”时，应把“理解有限重试时间”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

把接收与长任务分开

快速完成验证、记录和内部排队，不要在 Webhook HTTP 请求中等待耗时下游任务，以免连接超时造成重复投递。

处理“Webhook 重试与幂等基础”时，应把“把接收与长任务分开”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

记录可观测信息但不泄密

日志可记录安全事件标识、结果、尝试次数、耗时、错误分类和 traceId，不能记录签名秘密、原始 API Key 或完整敏感载荷。

处理“Webhook 重试与幂等基础”时，应把“记录可观测信息但不泄密”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

遵守业务事件边界

只处理文档列出的短信到达和已批准业务终态事件。号码分配或中间复核状态不是最终业务通知。

处理“Webhook 重试与幂等基础”时，应把“遵守业务事件边界”作为一个独立检查点，不要同时修改多个条件。记录页面现象、操作时间和相关业务编号，每次只执行一个有依据的步骤，并等待系统给出明确结果。

实际操作检查清单

1. 核对“使用公网 HTTPS 地址”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
2. 核对“处理前先验证签名”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
3. 核对“保存幂等事件身份”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
4. 核对“精确返回 SUCCESS”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
5. 核对“理解有限重试时间”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
6. 核对“把接收与长任务分开”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
7. 核对“记录可观测信息但不泄密”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。
8. 核对“遵守业务事件边界”对应的信息，保存可验证结果；只有下一步含义明确时才继续操作。

最终业务状态和账户流水是判断结果的依据。截图或客服沟通中不要发送密码、完整验证码、认证密钥、Access Token、API Key 或未遮挡的身份材料。更多说明可查看 MangoOTP 帮助中心。