如何使用个人密钥校验 Webhook 签名
为个人密钥设置一个值后,Chaingateway 会以 X-Signature 请求头对每个 Webhook 签名。本文说明 HMAC 的工作原理、Node.js 校验示例、如何测试处理程序、如何轮换密钥,以及签名不覆盖哪些内容。
审核: Maurice Sobiera
个人密钥是您在 Chaingateway 个人资料中设置的密钥。设置后,每个 Webhook 都会带上 X-Signature 请求头,其值为交易 ID 的 HMAC-SHA256 签名,并经 Base64 编码。服务器重新计算并比对该值,即可确认请求来自 Chaingateway。
为什么 Webhook 需要签名?
Webhook 接收端是一个公开 URL,任何知道它的人都可以向其发送请求。如果不做校验,伪造的“已收到付款”请求就可能让商品放行或让账户入账。共享密钥可以解决这个问题。只有 Chaingateway 和您的服务器知道该密钥,因此只有它们能生成匹配的签名。该构造是 HMAC,由 RFC 2104 定义:一种哈希函数与密钥的组合。
如何设置个人密钥?
在控制台中打开个人资料设置,找到 Webhook 个人密钥卡片,然后点击“Set Personal Secret”。如需替换现有密钥,请点击“Regenerate Secret”。文档中有两点细节值得注意:
- 首次设置密钥后,所有发出的 Webhook 都会启用
X-Signature请求头。在依赖它之前,请确保您的服务器能够接收并校验该请求头。 - 重新生成的密钥会立即生效。请在点击之前或同时更新您的处理程序,否则有效通知将无法通过校验。
签名是如何生成的?
文档中的步骤分为三步。从 Webhook 负载中读取 txid 字段。以您的个人密钥为密钥、以 txid 字符串为消息,计算 HMAC-SHA256。将结果进行 Base64 编码,并与请求头比对。负载示例如下(来自 Webhook 指南):
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}如何在服务器上校验签名?
根据 txid 重新计算 HMAC,并以恒定时间与请求头比对。下面的 Express 处理程序就是这样做的。它从环境变量读取密钥,拒绝缺失或长度错误的请求头,并且只对有效请求返回 200:
const crypto = require('crypto');const express = require('express');
const app = express();app.use(express.json());
function isValid(txid, received, secret) { const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64'); const a = Buffer.from(expected); const b = Buffer.from(received || ''); // timingSafeEqual throws when lengths differ, so check first return a.length === b.length && crypto.timingSafeEqual(a, b);}
app.post('/hooks/deposit', (req, res) => { const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET); if (!ok) return res.sendStatus(401); // process req.body.txid, deduplicate on it, then acknowledge res.sendStatus(200);});
app.listen(3000);文档还提供了 Python、Java 和 PHP 版本。在 Python 中,比对时请使用 hmac.compare_digest。在 Node.js 中,crypto.timingSafeEqual 完成同样的工作。普通的 == 比对可能泄露时间信息。
如何测试处理程序?
自行计算签名,并向本地服务器发送一条模拟通知。下面的 openssl 命令会生成处理程序所期望的同一个 Base64 HMAC。请使用测试密钥,切勿使用真实密钥:
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \ -H "Content-Type: application/json" \ -H "X-Signature: $SIG" \ -d "{\"txid\": \"$TXID\"}"使用 CG_PERSONAL_SECRET=test-secret 启动服务器。请求将返回 200。如果修改密钥或签名中的一个字符,则返回 401。每次部署处理程序后都应重新运行此测试,重新生成真实密钥后也应再次运行。
签名不覆盖哪些内容?
签名只覆盖交易 ID,不包含其他内容。按照文档中的构造方式,只有 txid 会被纳入 HMAC。由此产生两点后果:
- 有效的签名只能证明 Chaingateway 发送了该交易的通知,并不能证明正文中的
amount、to或contractaddress未被更改。如果这些字段决定了付款,请将它们与链上数据或订单的预期值进行核对。 - 同一笔交易可能被多次送达,例如您要求重发失败的通知之后。每份副本都带有相同的有效签名。请以
txid去重。
Webhook 不会自动重试。失败的通知按链列出,您需要为每条通知请求重发。Solana 没有 Webhook。在有 Webhook 的链上,签名方式完全相同。
如何在不丢失通知的情况下轮换密钥?
重新生成的密钥会立即生效,因此步骤的顺序很重要。让处理程序在短时间内同时接受两个密钥,然后再重新生成:
- 部署一个处理程序版本:先尝试当前密钥;如果校验失败,再尝试第二个可选的
CG_PERSONAL_SECRET_NEXT。 - 在个人资料中重新生成密钥,并复制新值。
- 将新值写入
CG_PERSONAL_SECRET_NEXT,然后重新部署。 - 在测试网上发起一笔测试转账,并确认处理程序能够接受它。
- 一天之后,将新密钥提升为
CG_PERSONAL_SECRET,并删除旧密钥。
文档没有说明轮换之后,重发的通知由哪个密钥签名。请在失败通知列表清空之前,保持双密钥的过渡期。
未设置密钥时会发生什么?
此时,Webhook 会在不带 X-Signature 请求头的情况下发送。您的处理程序不得将缺失的请求头视为有效。请按环境分别决定:在生产环境中,设置密钥后拒绝没有签名的请求;在本地测试环境中,可以允许这类请求。该请求头也是判断密钥是否生效的方式:如果通知中没有它,说明您的账户没有设置密钥。
完整参考资料在哪里?
Webhook 安全指南列出了上述步骤,并提供四种语言的代码。Webhook 指南则说明如何创建 Webhook 和接收端。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。