com.xpay.sdk.intl

Class XPayIntlWebhookVerifier

java.lang.Object

com.xpay.sdk.intl.XPayIntlWebhookVerifier

public final class XPayIntlWebhookVerifier
extends Object

国际版 Webhook 请求验签工具。

商户应先按 Webhook-Secret-Id 选择本地保存的 Webhook Secret，再使用投递 Timestamp、 Nonce 和原始 Body 的三行协议验签。工具不解析事件、不选择密钥、不保存业务状态；验签失败必须 fail-close，并在验签通过后由业务按 eventId 幂等消费。

Method Summary

Modifier and Type	Method and Description
static String	sign(String timestamp, String nonce, byte[] rawBody, String webhookSecret) 生成 Webhook 签名。
static String	sign(String timestamp, String nonce, String rawBody, String webhookSecret) 生成 UTF-8 文本 Body 的 Webhook 签名。
static boolean	verify(String timestampHeader, String nonceHeader, String signatureHeader, byte[] rawBody, String webhookSecret, long toleranceSeconds) 使用原始 Body 字节校验 Webhook 签名。
static boolean	verify(String timestampHeader, String nonceHeader, String signatureHeader, String rawBody, String webhookSecret, long toleranceSeconds) 使用未改写的 UTF-8 Body 文本校验 Webhook 签名。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

verify

public static boolean verify(String timestampHeader,
                             String nonceHeader,
                             String signatureHeader,
                             byte[] rawBody,
                             String webhookSecret,
                             long toleranceSeconds)

使用原始 Body 字节校验 Webhook 签名。

Header 缺失、时间戳超窗、签名格式错误或 Body 被修改时均返回 false，不会把密钥写入异常。 方法无事务、缓存、网络或异步副作用，可由接收服务并发调用。

Parameters:

timestampHeader - Webhook Timestamp Header

nonceHeader - Webhook Nonce Header

signatureHeader - Webhook Signature Header

rawBody - 实际收到且未经解析或重编码的 Body 字节

webhookSecret - Webhook-Secret-Id 对应的 Webhook Secret

toleranceSeconds - 与本机 Unix 时间允许的最大偏差秒数，必须大于零

Returns:

时间戳和签名均有效时返回 true，否则返回 false

verify

public static boolean verify(String timestampHeader,
                             String nonceHeader,
                             String signatureHeader,
                             String rawBody,
                             String webhookSecret,
                             long toleranceSeconds)

使用未改写的 UTF-8 Body 文本校验 Webhook 签名。

若框架能够提供原始字节，应优先使用字节重载；本方法不会解析 JSON，不访问数据库或缓存，验签失败 统一返回 false。

Parameters:

timestampHeader - Webhook Timestamp Header

nonceHeader - Webhook Nonce Header

signatureHeader - Webhook Signature Header

rawBody - 未改写的 UTF-8 Body 文本

webhookSecret - Webhook-Secret-Id 对应的 Webhook Secret

toleranceSeconds - 时间戳最大允许偏差秒数，必须大于零

Returns:

验签通过返回 true，否则返回 false

sign

public static String sign(String timestamp,
                          String nonce,
                          byte[] rawBody,
                          String webhookSecret)

生成 Webhook 签名。

该方法用于本地测试和平台互操作向量；生产接收流程只需调用 verify(java.lang.String, java.lang.String, java.lang.String, byte[], java.lang.String, long)。原文固定为时间戳、Nonce、 原始 Body 三行，每行后都带换行；方法无网络、事务、缓存或异步副作用。

Parameters:

timestamp - 投递 Unix 秒级时间戳

nonce - 投递随机串

rawBody - 原始 Webhook Body 字节

webhookSecret - Webhook Secret

Returns:

v1= 加 64 位小写十六进制签名

Throws:

XPayIntlException - 参数含换行、密钥为空或加密算法异常时抛出

sign

public static String sign(String timestamp,
                          String nonce,
                          String rawBody,
                          String webhookSecret)

生成 UTF-8 文本 Body 的 Webhook 签名。

本重载便于本地示例和测试；不会解析或格式化 JSON，也不访问网络、数据库或缓存。

Parameters:

timestamp - 投递 Unix 秒级时间戳

nonce - 投递随机串

rawBody - 未改写的 UTF-8 Body 文本

webhookSecret - Webhook Secret

Returns:

v1= 加 64 位小写十六进制签名

Throws:

XPayIntlException - 参数含换行、密钥为空或加密算法异常时抛出