跳转到内容

创建用于存款通知的区块链 Webhook

要接收 Chaingateway 的存款通知,你需要两个部分:服务器上的接收端点,以及用 POST /api/v2/{chain}/webhooks 创建的 webhook。当交易匹配 webhook 的筛选条件时,Chaingateway 会向你的端点发送一个带交易数据的 HTTP POST 请求。本教程针对 TRON 上的 TRC20 入账搭建这两部分。同样的步骤适用于 Ethereum、BNB Smart Chain、Polygon、Arbitrum 和 Bitcoin。Solana 没有 webhook。

如果想先了解概念和 payload 格式,请先阅读 Webhooks。你还需要快速入门中的 API token。

教程步骤:编写接收端,让它能从互联网访问,创建 webhook,发送测试 payload,处理投递失败 1. 编写接收端 返回 200 的 POST 端点 2. 让它可被访问 公开的 HTTPS URL 3. 创建 webhook POST /api/v2/tron/webhooks,带 url 和筛选条件 4. 用 payload 测试 用 curl 请求你自己的接收端 5. 处理失败 列出失败的通知并重发
步骤 1 和 2 在步骤 3 之前,因为第一个事件到达时 URL 必须已经可用。

接收端是一个服务器端点,接受带 JSON 请求体的 HTTP POST 请求,并返回状态码 200。处理函数要保持简短:保存 payload,立即响应,把耗时的工作放到队列或后台任务中稍后完成。下面的示例记录 payload 并确认收到。

const express = require('express');
const app = express();
const port = 3000;
app.use(express.json());
app.post('/webhook', (req, res) => {
console.log('Received webhook:', req.body);
res.status(200).send('Webhook received');
});
app.listen(port, () => {
console.log(`Webhook receiver listening at http://localhost:${port}`);
});

Chaingateway 只能访问公开的 URL。开发期间,请通过隧道暴露本地端口,并把隧道的 HTTPS 地址用作 webhook 的 url。在处理每个请求之前,请先校验其签名,方法见 Webhook 安全。

向 POST /api/v2/tron/webhooks 发送接收端的 url 和一个筛选条件。筛选条件决定哪些交易会触发通知。

  • url(必填):你的接收端地址,必须是有效的 URL。
  • from 和 to:发送方和接收方地址,Tron 格式。两者至少要提供一个,除非改为提供 contractaddress 和 token_id。
  • contractaddress:要跟踪的代币的合约。
  • token_id:NFT 的 token id。
  • type:TRX、TRC10、TRC20、TRC721 之一。
  • reference:你自己的标签,最多 255 个字符,例如订单号。

示例监控某一种代币向某一个存款地址的 TRC20 转账。

Terminal window
curl --request POST \
--url https://app.chaingateway.io/api/v2/tron/webhooks \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
"url": "https://example.com/webhook",
"to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"type": "TRC20",
"reference": "order-1042"
}'

响应的状态码为 201,webhook 的 id 在 data.webhook 中。请保存这个 id,因为更新或删除该 webhook 时需要它。

{
"status": 201,
"ok": true,
"message": "Webhook created",
"data": {
"webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46"
}
}

在其他链上,路径和 type 的取值会有变化。Ethereum 和 Arbitrum 接受 ETH、ERC20 和 ERC721,Polygon 接受 MATIC、ERC20 和 ERC721,BNB Smart Chain 接受 BNB、BEP20 和 BEP721,Bitcoin 只接受 url、from 和 to。EVM 链上的地址必须符合 0x 后跟 40 个十六进制字符的格式。要在测试网上测试,请在创建请求中添加请求头 X-Network: testnet。

真实存款到账之前,如何测试接收端?

Section titled “真实存款到账之前,如何测试接收端?”

用 curl 向你自己的端点发送一条示例通知。下面的请求体与真实通知的字段相同。如果你的接收端记录了它并返回 200,就说明端点工作正常。之后再向被监控的地址发送一笔小额测试网转账,查看真实的事件。

Terminal window
curl --request POST \
--url https://example.com/webhook \
--header 'Content-Type: application/json' \
--data '{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}'

如何处理投递失败的通知和旧的 webhook?

Section titled “如何处理投递失败的通知和旧的 webhook?”

Chaingateway 不会自动重试失败的投递。GET /api/v2/tron/webhooks/notifications/failed 会列出它们,POST /api/v2/tron/webhooks/notifications/{id}/retry 会重新发送其中一条。用 GET /api/v2/tron/webhooks 列出你的 webhook,用 PUT /api/v2/tron/webhooks/{id} 修改,用 DELETE /api/v2/tron/webhooks/{id} 删除。webhook 完成任务后请将其删除,例如某个订单的付款到账之后。

  • 接收端必须可公开访问,并接受 HTTP POST 请求。
  • 用 X-Signature 请求头验证每个请求的来源和完整性。
  • 让接收端具有幂等性。用 txid 识别你已经处理过的通知。
  • 把 API token 保存在密钥存储中,不要写进接收端的源代码。