USDT 收款回调验签:HMAC-SHA256 Webhook 签名验证实战

回调地址是公开的,谁都能伪造一条「已支付」通知。本文讲清 HMAC-SHA256 加时间戳的验签原理、原始请求体的常见坑,以及防重放、幂等去重和重试的正确处理方式。

TTillCrypto 团队6 分钟阅读

Webhook 回调是支付网关告诉你「这笔订单已到账」的方式,但它同时也是一个公网地址,谁都能往里 POST。如果不做回调签名验证,一条真实的到账通知和别人随手敲的一行 curl,在你的服务器看来没有任何区别。

这篇文章讲清楚 HMAC 签名回调的原理、最容易踩的坑(验签总是失败,或者本该失败却通过了),以及怎么处理重放、重复推送和重试。示例代码有 Node.js、Python 和 PHP 三种,以 X-TillCrypto-Signature 请求头为例,其他大多数网关的思路也一样。

为什么 USDT 收款的回调必须验签

回调地址算不上秘密。它通常是 /webhooks/payment 这类一猜就中的路径,还会出现在日志、截图和工单里。迟早会有人往这个地址发一条这样的请求:

json
{ "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(密钥, 消息),把结果放进请求头;你收到后用同样的方法再算一遍,两边对得上,就说明请求是真的。

一次推送大概长这样:

http
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

下面三段代码的步骤完全一样:

  1. 先拿到原始请求体(字节),在任何 JSON 解析之前。
  2. 把请求头拆成 t 和 v1。
  3. t 与本机时间相差超过 300 秒就拒绝。
  4. 用完整的密钥字符串(包括 whsec_ 前缀)作为 key,对 t + . + 原始请求体计算 HMAC-SHA256。
  5. 用恒定时间比较算出的结果和 v1。
  6. 验签通过后,才解析 JSON、处理业务。

Node.js(Express)

javascript
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)

python
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 "", 200

PHP

php
<?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 只记录一次,业务更新带条件执行。

sql
-- 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 小时

最后一次仍失败的事件会标记为失败,可以在后台手动重发。

参考资料

在你的网站上收 USDT

托管收银台、签名回调、测试模式。收款零手续费,没有月费。