验证 Webhook 签名（HMAC）

使用 HMAC（基于哈希的消息验证码）进行 Webhook 签名验证可确保发送到服务器的 Webhook 确实来自 Yuno，并且在传输过程中未被拦截或修改。这比 OAuth 等验证方法多了一层安全保障。

OAuth 提供身份验证（验证谁在发送请求），而 HMAC 签名则提供身份验证：

数据完整性：确认网络钩子有效载荷未被篡改
真实性：验证网络钩子是否真正来自 Yuno
保护：防范中间人攻击和重放攻击
合规性：符合处理敏感支付数据的安全要求

HMAC 签名的工作原理

当 Yuno 向服务器发送 webhook 时：

生成签名：Yuno 使用 SHA-256 算法对 webhook 有效载荷和客户密钥进行散列，从而生成 HMAC 签名。
加入页眉:签名包含在 x-hmac-signature HTTP 标头
验证：服务器从标头中提取签名，使用相同的有效载荷和秘钥重新创建签名，然后比较
验证：如果签名匹配，则表示网络钩子是真实的，未被篡改

配置

要启用 HMAC 签名验证，请在Yuno 面板中创建或编辑 webhook 时选中使用 HMAC 验证。

有关访问网络钩子配置面板的逐步说明，请参阅配置网络钩子。

HMAC 的变化

启用 HMAC 签名验证时，Yuno 网络钩子会包含一个额外的 x-hmac-signature HTTP 头信息。网络钩子的 JSON 有效负载保持不变。

使用 HMAC 的网络钩子请求示例

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
x-api-key: your-api-key
x-secret: your-secret
x-hmac-signature: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

{
  "type": "payment",
  "type_event": "payment.purchase",
  "account_id": "2c05976d-1234-1234-1234-6421883de48d",
  "retry": 0,
  "version": 2,
  "data": {
    "payment": {
      "id": "a546c566-1703-4fba-b334-c46e89bc97f7",
      "status": "SUCCEEDED"
    }
  }
}

HMAC 签名的工作原理

配置

HMAC 的变化

使用 HMAC 的网络钩子请求示例

相关文件