概述

在与 Subotiz 系统集成时，商户可通过配置 Webhook 通知端点，实时接收账户关联事件，以便后端系统触发对应的业务逻辑处理（如支付状态更新、订阅状态变更等）。

​

通知原理

当 Subotiz 系统触发特定事件时，将向配置的 Webhook 通知端点发送 HTTPS POST 请求。请求包含以下关键要素：

• 请求负载：符合 JSON 格式规范的结构化事件对象，包含事件标识、类型及具体业务数据；
• 请求头信息：包含用于鉴权与请求标识的特定头部（如 X-Timestamp 时间戳、X-Signature 签名等）；

​

请求组成

​

请求头部

​

请求体结构

​

事件处理规范

​

可靠性验证

接收事件前需通过以下步骤验证请求合法性：

1. 提取参数：从请求头获取 X-Timestamp 时间戳（记为timestamp），并获取原始请求体内容（记为body）；
2. 构造签名原串：格式为${timestamp}.${body}；
3. 计算签名：使用 Subotiz 分配的 API Key 作为密钥，通过 HMAC-SHA256 算法计算签名值； 示例代码: GO
   // 计算签名
   func CalcSignature(timestamp int64, body []byte, secret string) string {
       mac := hmac.New(sha256.New, []byte(secret))
       mac.Write([]byte(fmt.Sprintf("%d", timestamp)))
       mac.Write([]byte("."))
       mac.Write(body)
       return hex.EncodeToString(mac.Sum(nil))
   }
   
4. 比对验证：将计算得到的签名与请求头中的 X-Signature 值比对，一致则为合法请求。

​

密钥轮换期间的处理

发起密钥轮换后，Subotiz 在过渡期内会使用旧密钥对 Webhook 请求进行签名；旧密钥过期后自动切换至新密钥。 建议在过渡期内，接收端同时支持新旧两个密钥验签，处理流程如下：

1. 先使用旧密钥计算签名，与 X-Signature 比对；
2. 若旧密钥验签失败，再使用新密钥重新验签；
3. 两者均失败时，视为非法请求拒绝处理。

这样可确保密钥切换过渡期间 Webhook 事件不丢失。

​

处理要求

• 幂等性：基于事件 id（唯一标识）实现重复事件的幂等处理，避免重复操作；
• 事件过滤：根据事件 type 字段识别关注的事件类型，非关注类型直接返回 200 状态码；
• 顺序无关性：系统不保证事件顺序，关键业务需通过 API 主动查询同步最新状态。

​

响应与重试机制

• 成功响应：事件处理完成后需返回 HTTP 200 状态码，标识事件处理成功；
• 失败重试：若响应状态码非 200 或超时，系统将在 48 小时内执行 16 次退避重试（起始间隔时间为 1 min，每次间隔时间翻倍，最大间隔 4 小时）。