Webhook 如何自动处理加密货币充值
Webhook 如何检测加密货币充值:Webhook 与轮询的区别、通知负载的字段、HMAC 签名校验,以及如何处理漏收的通知。文中包括创建 Webhook 的请求、负载示例、一段最小化的接收端代码,以及在测试网上的验证方法。
审核: Maurice Sobiera
Webhook 是服务在某个事件发生时发送给您服务器的 HTTP 请求。对于加密货币充值,该事件是一笔与您所监控地址相匹配的交易。Chaingateway 会把交易详情发送到您的端点,您的代码随即为客户入账。这取代了反复轮询区块链 API 以查找新交易的做法。
什么是 Webhook?
Webhook 是基于 HTTP 的回调。您把一个 URL 交给发送方,当预定义的事件发生时,发送方会向该 URL 发出 POST 请求。请求的正文就是负载。可以把这个 URL 想象成一个电话号码,发送方在任何事情发生时都会拨打它。
Webhook 与 API 是交换数据的两种方式。使用 API 时,您主动拉取:您的代码按计划请求数据,并检查是否有变化。使用 Webhook 时,由服务商主动推送:它在事件发生的那一刻联系您。推送可以减少请求次数,并缩短延迟。拉取仍有其作用,因为 Webhook 只告诉您某件事发生了。如果您需要完整的记录,或想进行核对,就向 API 请求。
对于充值,应使用 Webhook 还是轮询?
使用 Webhook 快速获知充值,使用 API 对其进行验证和对账。两者配合得很好。
| 方式 | 优势 | 劣势 |
|---|---|---|
| 轮询 API | 由您控制时机,停机后可以续传 | 浪费请求,延迟与轮询间隔一样长 |
| Webhook | 交易被发现后很快收到通知 | 如果您的端点宕机,通知可能丢失 |
在 Chaingateway 上,Webhook 适用于比特币、以太坊、BNB 智能链、Tron、Polygon 和 Arbitrum。Solana 不支持 Webhook,因此在那里您需要查询交易。
如何设置充值 Webhook?
先创建一个接收端点,再为您想监控的地址注册 Webhook。该端点必须能从公共互联网访问。您无需允许 Chaingateway 的 IP 地址,因为该服务像任何其他客户端一样调用您的公共 URL。
Webhook 需要 url,并且至少需要 from 或 to 之一。可选过滤条件包括 contractaddress、token_id 和 type,在以太坊上 type 可为 ETH、ERC20 或 ERC721。您还可以设置最多 255 个字符的 reference,例如您的订单号。以下请求监控发往某一地址的 ERC-20 代币(此处为 USDT 合约)充值。
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/hooks/deposits", "type": "ERC20", "contractaddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "reference": "order-1042" }'调用成功时返回状态码 201,并在 data.webhook 中返回 Webhook ID。请在客户付款之前创建 Webhook,这样付款就不可能在监控建立之前发生。
通知包含什么?
每个 POST 都包含将付款与订单匹配所需的字段。以下示例来自 Chaingateway 文档,是一笔 TRC20 转账。
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "datetime": "2024-09-25 14:48:27", "tokenid": null, "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}txid 用于标识交易,webhook_id 则告诉您是哪一个监控触发了通知。请以唯一索引保存 txid。如果同一通知收到两次,第二次插入会失败,您随即跳过即可。
如何验证通知是真实的?
在信任负载之前,请先检查 X-Signature 请求头。Chaingateway 以您的个人密钥为键,对 txid 计算 SHA-256 的 HMAC,并以 Base64 编码发送结果。HMAC 的定义见 RFC 2104。您的服务器重复该计算,并使用恒定时间比较来对比两个值。
个人密钥在您的个人资料设置中配置。密钥生效后,所有外发的 Webhook 都会附带该请求头。签名文档提供了 Python、Java、PHP 和 JavaScript 的验证代码。
最小化的接收端是什么样的?
接收端校验签名,只记录一次事件,并尽快作出响应。下面这个 Express 示例把见过的交易 ID 保存在内存中,以保持简短。在生产环境中,请使用在 txid 上设有唯一索引的数据库表。
const crypto = require('crypto');const express = require('express');
const app = express();const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => { const { txid, to, amount } = req.body; const expected = crypto .createHmac('sha256', process.env.PERSONAL_SECRET) .update(txid) .digest('base64'); const received = req.get('X-Signature') || '';
const valid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) { seen.add(txid); // credit the order that belongs to the address `to` for `amount` } res.sendStatus(200);});
app.listen(3000);请先在测试网上测试接收端。创建 Webhook 时添加 X-Network: testnet 请求头,然后向被监控的地址发送一笔小额测试转账。通知应携带该转账的 txid 到达。文档建议在付款发生前才创建 Webhook,因此请在分配地址时创建它。
如果我的服务器宕机了会怎样?
通知不会自动再次发送。如果您的端点未接受某条通知,它会出现在失败通知列表中,列表地址为 GET /api/v2/{chain}/webhooks/notifications/failed。您可以对每一条记录使用 POST /api/v2/{chain}/webhooks/notifications/{id}/retry 触发重新投递。如果重试仍然失败,该记录会回到列表中。
在存储好事件之后,请立即返回成功状态码,把耗时的工作放到之后再做。RFC 9110 将 2xx 状态码类别定义为表示请求已被接收并接受。请定期检查失败列表,并将您的记录与 API 进行对账,以免缺口长期未被发现。Webhook 投递指南更详细地介绍了重复和顺序问题。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。