事件通知与验签规范 (Webhook Events)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;

public class DsignWebhookVerifier {

    public static boolean verifyWebhook(
            String secret,
            String timestampMs,
            byte[] rawBody,
            String receivedSignature
    ) {
        try {
            // 1. 校验时间戳合法性与 300 秒偏差
            long ts = Long.parseLong(timestampMs);
            long nowMs = System.currentTimeMillis();
            if (Math.abs(nowMs - ts) > 300000L) {
                return false;
            }

            // 2. 使用 HMAC-SHA256 计算期望签名
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec keySpec = new SecretKeySpec(
                    secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"
            );
            mac.init(keySpec);

            mac.update((timestampMs + ".").getBytes(StandardCharsets.UTF_8));
            mac.update(rawBody);

            byte[] computedHmac = mac.doFinal();
            String expected = Base64.getEncoder().encodeToString(computedHmac);

            // 3. 常量时间安全比对防侧信道攻击
            return MessageDigest.isEqual(
                    expected.getBytes(StandardCharsets.UTF_8),
                    receivedSignature.getBytes(StandardCharsets.UTF_8)
            );
        } catch (Exception e) {
            return false;
        }
    }
}

function verifyWebhook(
    string $secret,
    string $timestampMs,
    string $rawBody,
    string $receivedSignature
): bool {
    // 1. 校验时间戳是否为正整数及偏差在 300 秒以内
    if (!ctype_digit($timestampMs)) {
        return false;
    }
    $nowMs = (int)(microtime(true) * 1000);
    if (abs($nowMs - (int)$timestampMs) > 300000) {
        return false;
    }

    // 2. 拼接待签字符串并使用 HMAC-SHA256 计算签名
    $stringToSign = $timestampMs . '.' . $rawBody;
    $expected = base64_encode(
        hash_hmac('sha256', $stringToSign, $secret, true)
    );

    // 3. 常量时间安全比对
    return hash_equals($expected, $receivedSignature);
}

import hmac
import hashlib
import base64
import time

def verify_webhook(
    secret: str,
    timestamp_ms: str,
    raw_body: bytes,
    received_signature: str
) -> bool:
    # 1. 校验时间戳有效性与偏差
    try:
        ts = int(timestamp_ms)
        now_ms = int(time.time() * 1000)
        if abs(now_ms - ts) > 300000:
            return False
    except ValueError:
        return False

    # 2. 拼接待签字节串并计算 HMAC-SHA256
    payload = f"{timestamp_ms}.".encode('utf-8') + raw_body
    computed = hmac.new(secret.encode('utf-8'), payload, hashlib.sha256).digest()
    expected = base64.b64encode(computed).decode('utf-8')

    # 3. 常量时间防时序攻击比对
    return hmac.compare_digest(expected, received_signature)

const crypto = require('crypto');

function verifyWebhook(secret, timestampMs, rawBodyBuffer, receivedSignature) {
    // 1. 校验时间戳合法性与 300 秒偏差
    const ts = parseInt(timestampMs, 10);
    if (isNaN(ts) || Math.abs(Date.now() - ts) > 300000) {
        return false;
    }

    // 2. 拼接 Buffer 并计算 HMAC-SHA256
    const prefix = Buffer.from(`${timestampMs}.`, 'utf8');
    const payload = Buffer.concat([prefix, rawBodyBuffer]);
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('base64');

    // 3. 常量时间安全比对
    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(receivedSignature)
    );
}