← 博客
10 分钟阅读
|
发布于
|
更新于

Webhook 如何自动处理加密货币充值

Webhook 如何检测加密货币充值:Webhook 与轮询的区别、通知负载的字段、HMAC 签名校验,以及如何处理漏收的通知。文中包括创建 Webhook 的请求、负载示例、一段最小化的接收端代码,以及在测试网上的验证方法。

章节
C
Chaingateway Team
区块链专家

审核: 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 合约)充值。

Terminal window
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 参考。

C
Chaingateway Team
区块链专家

Chaingateway 团队致力于为全球开发者简化区块链集成。