USDT 收款回调验签:HMAC-SHA256 Webhook 签名验证实战
回调地址是公开的,谁都能伪造一条「已支付」通知。本文讲清 HMAC-SHA256 加时间戳的验签原理、原始请求体的常见坑,以及防重放、幂等去重和重试的正确处理方式。
Webhook 回调是支付网关告诉你「这笔订单已到账」的方式,但它同时也是一个公网地址,谁都能往里 POST。如果不做回调签名验证,一条真实的到账通知和别人随手敲的一行 curl,在你的服务器看来没有任何区别。
这篇文章讲清楚 HMAC 签名回调的原理、最容易踩的坑(验签总是失败,或者本该失败却通过了),以及怎么处理重放、重复推送和重试。示例代码有 Node.js、Python 和 PHP 三种,以 X-TillCrypto-Signature 请求头为例,其他大多数网关的思路也一样。
为什么 USDT 收款的回调必须验签
回调地址算不上秘密。它通常是 /webhooks/payment 这类一猜就中的路径,还会出现在日志、截图和工单里。迟早会有人往这个地址发一条这样的请求:
{ "type": "payment.paid", "data": { "order_id": "ORDER-10001", "status": "paid" } }如果你的代码直接相信这个请求体,一笔没付钱的订单就被标成了已支付。卖激活码、下载链接、会员充值这类自动发货的虚拟商品,等你发现时货早就发出去了,所以用 USDT 卖虚拟商品时,回调处理更要写严谨。
HTTPS 解决不了这个问题,它保护的是传输过程,不能证明对方是谁。IP 白名单有一点用,但网关一换机房就失效,而且不少网关(包括 TillCrypto)本来就不提供固定的出口 IP 列表。用户跳回 success_url 更不能当作到账凭证,那个地址谁都能手动打开(详见网站如何接入 USDT 收款)。
签名能给你的东西不多,但恰好是你需要的:发送方确实知道只有你和网关才有的密钥;请求体从签名那一刻起,一个字节都没被改过。
HMAC-SHA256 回调签名的原理
HMAC 是一种带密钥的哈希。你和网关共享一个签名密钥(TillCrypto 的密钥以 whsec_ 开头)。每次推送时,网关计算 HMAC-SHA256(密钥, 消息),把结果放进请求头;你收到后用同样的方法再算一遍,两边对得上,就说明请求是真的。
一次推送大概长这样:
POST /webhooks/tillcrypto HTTP/1.1
Content-Type: application/json
X-TillCrypto-Event-Id: evt_Xk2...
X-TillCrypto-Signature: t=1794444780,v1=5f1c0d...e9a2| 字段 | 含义 | 你要做什么 |
|---|---|---|
t |
本次推送签名时的 Unix 时间戳(秒) | 和本机时间差太多就拒绝 |
v1 |
HMAC-SHA256(密钥, "<t>.<原始请求体>") 的十六进制 |
自己重算,并用恒定时间比较 |
X-TillCrypto-Event-Id |
事件 ID,每次重试都相同 | 用来去重 |
时间戳被放进签名内容里,这是故意的。如果它只是一个单独的请求头,攻击者拿到一条旧请求后改一下 t 就能冒充新请求;签进去以后,改 t 签名就对不上了。v1= 这个前缀则是给以后升级签名算法留的余地,不会影响现有代码。
支付回调验签代码:Node.js、Python、PHP
下面三段代码的步骤完全一样:
- 先拿到原始请求体(字节),在任何 JSON 解析之前。
- 把请求头拆成
t和v1。 t与本机时间相差超过 300 秒就拒绝。- 用完整的密钥字符串(包括
whsec_前缀)作为 key,对t+.+ 原始请求体计算 HMAC-SHA256。 - 用恒定时间比较算出的结果和
v1。 - 验签通过后,才解析 JSON、处理业务。
Node.js(Express)
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.TILLCRYPTO_WEBHOOK_SECRET; // whsec_...
if (!SECRET) throw new Error('TILLCRYPTO_WEBHOOK_SECRET is not set');
const TOLERANCE_SECONDS = 300;
function verifySignature(rawBody, header, secret) {
const parts = {};
for (const pair of (header || '').split(',')) {
const i = pair.indexOf('=');
if (i > 0) parts[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
}
const { t, v1 } = parts;
if (!t || !/^\d+$/.test(t) || !v1) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
const received = Buffer.from(v1, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
const app = express();
// 这个路由必须注册在全局 app.use(express.json()) 之前
app.post('/webhooks/tillcrypto', express.raw({ type: 'application/json' }), async (req, res) => {
const ok = Buffer.isBuffer(req.body) &&
verifySignature(req.body, req.get('X-TillCrypto-Signature'), SECRET);
if (!ok) return res.status(400).send('invalid signature');
const event = JSON.parse(req.body.toString('utf8'));
try {
await saveToInbox(event); // 你自己的代码:INSERT ... ON CONFLICT (event_id) DO NOTHING
} catch (err) {
console.error(err);
return res.sendStatus(500); // 没存下来,让网关稍后重试
}
res.sendStatus(200); // 发货等耗时操作交给后台任务
});
app.use(express.json()); // 其余接口照常使用 JSON 解析crypto.timingSafeEqual 遇到长度不同的两个 Buffer 会直接抛异常,所以要先比较长度。
Python(Flask)
import hashlib, hmac, json, os, time
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ["TILLCRYPTO_WEBHOOK_SECRET"].encode() # whsec_...
TOLERANCE_SECONDS = 300
def verify_signature(raw: bytes, header: str, secret: bytes) -> bool:
parts = {}
for pair in header.split(","):
key, sep, value = pair.strip().partition("=")
if sep:
parts[key] = value
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not (t.isascii() and t.isdigit()) or not v1:
return False
if abs(time.time() - int(t)) > TOLERANCE_SECONDS:
return False
expected = hmac.new(secret, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())
@app.post("/webhooks/tillcrypto")
def tillcrypto_webhook():
raw = request.get_data() # 原始字节,必须在解析 JSON 之前读取
if not verify_signature(raw, request.headers.get("X-TillCrypto-Signature", ""), SECRET):
return "invalid signature", 400
event = json.loads(raw)
save_to_inbox(event) # 你自己的代码;抛异常时 Flask 返回 500,网关会重试
return "", 200PHP
<?php
const TOLERANCE_SECONDS = 300;
function verify_signature(string $raw, string $header, string $secret): bool {
$parts = [];
foreach (explode(',', $header) as $pair) {
$kv = explode('=', trim($pair), 2);
if (count($kv) === 2) {
$parts[$kv[0]] = $kv[1];
}
}
$t = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';
if (!ctype_digit($t) || $v1 === '') {
return false;
}
if (abs(time() - (int) $t) > TOLERANCE_SECONDS) {
return false;
}
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
return hash_equals($expected, $v1);
}
$secret = getenv('TILLCRYPTO_WEBHOOK_SECRET');
if (!$secret) {
http_response_code(500); // 绝不能用空密钥验签
exit('webhook secret not configured');
}
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_TILLCRYPTO_SIGNATURE'] ?? '';
if (!verify_signature($raw, $header, $secret)) {
http_response_code(400);
exit('invalid signature');
}
$event = json_decode($raw, true);
try {
save_to_inbox($event); // 你自己的代码:按 event_id 插入,重复的忽略
} catch (Throwable $e) {
error_log((string) $e);
http_response_code(500); // 没存下来,让网关重试
exit;
}
http_response_code(200);PHP 这里的 try/catch 不是多余的。如果服务器开着 display_errors,未捕获的异常可能连同报错页面一起以 200 状态码返回,网关会以为推送成功,这条事件就丢了。
为什么要恒定时间比较?普通的 == 一遇到不同的字符就立刻返回,猜错得多的请求会比几乎猜对的请求快那么一点点。隔着网络想测出这点差别很难,但换成安全的比较函数没有任何成本。各语言都有现成的:crypto.timingSafeEqual、hmac.compare_digest、hash_equals。
验签总是失败?原始请求体和其他常见坑
本地测试好好的,一上线就验签失败,多半是下面几种情况之一:
- JSON 被重新序列化。 先解析再序列化,字节就变了:键的顺序、空格、
10.0和10,还有中和中(Python 的json.dumps默认会把中文转义成\uXXXX,JavaScript 的JSON.stringify不会)。差一个字节,HMAC 就完全不同。 - Express 中间件顺序。 如果
app.use(express.json())先执行,请求体已经被解析过了,路由上的express.raw会直接跳过,req.body是一个对象而不是原始 Buffer,验签次次失败。把回调路由放在全局解析器前面。 - Next.js 等框架。 App Router 里用
await request.text(),不要用request.json();Pages Router 要给这个接口关掉内置的 body parser。 - 密钥不对。 确认用的是包含
whsec_的完整密钥,.env里没有多出换行。在后台轮换密钥会立即生效,没有新旧并存的过渡期:之后的每一次推送,包括旧事件的重试,都用新密钥签名。服务器换上新密钥之前推送会失败,但都会重试,不会丢。 - 重定向。 TillCrypto 不跟随重定向,
http跳https、少了末尾斜杠导致的 301,都会被当成推送失败。后台要填最终地址。 - 服务器时间不准。 时钟偏差几分钟,所有回调都会被拒。记得开 NTP 同步。
签名不对时返回 4xx 并记日志,不要为了图清净返回 200。如果是你这边密钥配错了,改好之后后续重试自然会成功。
防重放与幂等:用事件 ID 去重
签名有效只能说明请求确实来自网关,不能说明你是第一次收到它。重复请求有两个来源:
- 重放攻击。 有人截获一条合法请求再发一遍。时间戳窗口把这个风险限制在几分钟内。
- 正常重试。 你其实已经处理完了,但响应太慢,比如超过了 TillCrypto 的 10 秒超时,网关就会用同一个事件 ID 再推一次。
两种情况一个办法:每个事件 ID 只记录一次,业务更新带条件执行。
-- Postgres 写法;MySQL 请改用 ? 占位符和 INSERT IGNORE
CREATE TABLE webhook_inbox (
event_id VARCHAR(64) PRIMARY KEY,
type TEXT NOT NULL,
payload TEXT NOT NULL,
received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
processed_at TIMESTAMP
);
-- 回调接口里
INSERT INTO webhook_inbox (event_id, type, payload)
VALUES ($1, $2, $3)
ON CONFLICT (event_id) DO NOTHING;
-- 后台任务里:只有一次执行能把订单改成 paid
UPDATE orders SET status = 'paid', paid_at = CURRENT_TIMESTAMP
WHERE id = $1 AND status IN ('pending', 'expired');UPDATE 影响行数为 0,说明这单已经是已支付,跳过发货即可。事件 ID 要取验签后请求体里的 event.id,而不是请求头里的,因为签名只覆盖请求体。
注意 WHERE 里带上了 expired。订单过期不等于彻底结束:收银台倒计时结束后 30 分钟内到账的付款,TillCrypto 照样入账;自动匹配不上的转账,在人工审核时也可能被归到一笔已过期的订单上。这两种情况你都会收到 payment.paid,客户是真的付了钱,不能因为订单「已过期」就不发货。
发货之前,后台任务还应该检查:
- 生产环境里
livemode必须是true,测试事件的livemode是false。 data.status是"paid",data.order_id能对上真实订单。data.amount和data.currency与你下单时的金额、币种一致。要比对的是data.amount(你要求的金额),而不是pay_amount:同金额订单并发时,pay_amount可能会多出一点点,比如 100.01。如果你在意少付,再看一眼received_amount,人工匹配的转账,它就是实际到账的金额。- 不认识的事件类型(包括后台发的
webhook.test)标记为已处理后跳过,不要当成错误抛出。 - 状态只能往前走。订单一旦是
paid,晚到的旧事件不能再改动它。
过期后到账、少付等复杂情况,可以看加密货币收款的各种边界情况。拿不准的时候,直接调 GET /v1/payments/{id} 查一次最稳妥。
先快速返回 2xx,再异步处理:重试机制
TillCrypto 最多等 10 秒(不少网关更短)。如果回调接口里要发邮件、生成激活码、调 ERP,全部做完再返回,总有一天会超时,触发一次你其实已经处理过的重试。
可靠的做法是:验签 → 入库 → 返回 2xx → 后台任务处理。 一定要先入库再返回。如果先返回了 200,还没存下来进程就挂了,这条事件就丢了,也不会再有重试。
推送失败(返回非 2xx、超时或连不上)时,TillCrypto 按下面的节奏重试:
| 第几次 | 距上次失败等待 | 距第一次推送大约 |
|---|---|---|
| 1 | 立即 | 0 |
| 2 | 1 分钟 | 1 分钟 |
| 3 | 5 分钟 | 6 分钟 |
| 4 | 15 分钟 | 21 分钟 |
| 5 | 1 小时 | 1 小时 21 分 |
| 6 | 6 小时 | 7 小时 21 分 |
| 7 | 24 小时 | 约 31 小时 |
最后一次仍失败的事件会标记为失败,可以在后台手动重发。