跳到主要内容

Webhook 验证

本文档说明如何验证接收到的 QI Tech webhook 请求的真实性和完整性。

Webhook 请求格式​

请求头​

字段描述
Authorization包含 JWT 令牌的签名头部

请求体​

标准 JSON 格式的 webhook 数据。

验证步骤​

1. 导入所需库​

根据您使用的编程语言，导入处理 JWT 和加密哈希的库。

2. 定义 QI Tech 公钥​

使用 QI Tech 提供的公钥对请求进行验证。

3. 解密 Authorization 头部​

AUTHORIZATION 头部包含一个 JWT 令牌，需要使用 QI Tech 公钥进行解密和验证。

4. 执行验证​

解密 JWT 后，请验证以下内容：

  • 方法（Method）：确认请求使用的 HTTP 方法正确
  • URI：确认请求的 URI 与预期一致
  • Payload MD5：对接收到的 body 计算 MD5 哈希值，并与 JWT 中的值进行对比
  • 时间戳（Timestamp）：确认时间戳在合理范围内，以防止重放攻击
import hashlib
import json
import jwt

QI_TECH_PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
<YOUR_QI_TECH_PUBLIC_KEY>
-----END PUBLIC KEY-----"""

def validate_webhook(authorization_header, request_body, method, uri):
    # 解密 JWT
    decoded = jwt.decode(
        authorization_header,
        QI_TECH_PUBLIC_KEY,
        algorithms=["ES512"]
    )
    
    # 计算 payload 的 MD5 哈希值
    body_string = json.dumps(request_body)
    md5_hash = hashlib.md5(body_string.encode()).hexdigest()
    
    # 解析签名字符串
    signature = decoded["signature"].split("\n")
    
    # 验证各字段
    assert signature[0] == method
    assert signature[1] == uri
    assert signature[2] == md5_hash
    
    return True