创建用于存款通知的区块链 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 接收端?
Section titled “如何编写 webhook 接收端?”接收端是一个服务器端点,接受带 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}`);});from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook(): data = request.get_json() print('Received webhook:', data) return jsonify({'status': 'Webhook received'}), 200
if __name__ == '__main__': app.run(port=3000)<?phpif ($_SERVER['REQUEST_METHOD'] === 'POST') { $data = file_get_contents('php://input'); $json = json_decode($data, true); file_put_contents('php://stderr', print_r($json, TRUE)); http_response_code(200); echo json_encode(['status' => 'Webhook received']);}<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ // Register the route in routes/api.php: // Route::post('/webhook', [WebhookController::class, 'handleWebhook']); public function handleWebhook(Request $request) { $data = $request->all(); file_put_contents('php://stderr', print_r($data, TRUE)); return response()->json(['status' => 'Webhook received'], 200); }}Chaingateway 只能访问公开的 URL。开发期间,请通过隧道暴露本地端口,并把隧道的 HTTPS 地址用作 webhook 的 url。在处理每个请求之前,请先校验其签名,方法见 Webhook 安全。
如何订阅区块链事件?
Section titled “如何订阅区块链事件?”向 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 转账。
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"}'import requests
url = "https://app.chaingateway.io/api/v2/tron/webhooks"payload = { "url": "https://example.com/webhook", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "type": "TRC20", "reference": "order-1042"}headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'}
response = requests.post(url, json=payload, headers=headers)print(response.json())const axios = require('axios');
const url = 'https://app.chaingateway.io/api/v2/tron/webhooks';const payload = { url: 'https://example.com/webhook', to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', type: 'TRC20', reference: 'order-1042'};const headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'};
axios.post(url, payload, { headers }) .then(response => { console.log(response.data); }) .catch(error => { console.error(error.response?.data ?? error); });<?phprequire 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();$response = $client->post('https://app.chaingateway.io/api/v2/tron/webhooks', [ 'headers' => [ 'Accept' => 'application/json', 'Authorization' => 'Bearer YOUR_API_TOKEN', ], 'json' => [ 'url' => 'https://example.com/webhook', 'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', 'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'type' => 'TRC20', 'reference' => 'order-1042' ]]);
echo $response->getBody();响应的状态码为 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,就说明端点工作正常。之后再向被监控的地址发送一笔小额测试网转账,查看真实的事件。
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 保存在密钥存储中,不要写进接收端的源代码。
- RFC 9110, HTTP Semantics 定义了接收端使用的 POST 方法和状态码。
- TRON TRC20 protocol interface 定义了 TRC20 通知背后的代币事件。
- Ethereum 代币标准 EIP-20 为 EVM 链上的 ERC-20 定义了同样的内容。