Создание блокчейн-вебхуков для депозитов
Чтобы получать от Chaingateway уведомления о депозитах, нужны принимающий эндпоинт на вашем сервере и вебхук, созданный через POST /api/v2/{chain}/webhooks. Когда транзакция соответствует фильтру вебхука, Chaingateway отправляет на ваш эндпоинт HTTP POST-запрос с данными транзакции. Руководство строит обе части для депозитов TRC20 в TRON. Те же шаги подходят для Ethereum, BNB Smart Chain, Polygon, Arbitrum и Bitcoin. В Solana вебхуков нет.
Сначала прочитайте раздел Как работают вебхуки платежей в блокчейне, если вам нужны основные понятия и формат payload. Для работы нужен API-токен, его описывает Быстрый старт.
Как написать приёмник вебхука?
Заголовок раздела «Как написать приёмник вебхука?»Приёмник — это эндпоинт сервера, который принимает HTTP POST-запросы с JSON-телом и отвечает статусом 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-адрес туннеля как url вебхука. Проверяйте подпись каждого запроса, прежде чем действовать, как описано в разделе Проверка подписи вебхуков с помощью HMAC.
Как подписаться на событие блокчейна?
Заголовок раздела «Как подписаться на событие блокчейна?»Отправьте POST /api/v2/tron/webhooks с url вашего приёмника и фильтром. Фильтр определяет, какие транзакции вызывают уведомление.
url(обязательный): адрес вашего приёмника. Должен быть допустимым URL.fromиto: адрес отправителя и получателя в формате Tron. Нужен хотя бы один из них, если вместо них не заданыcontractaddressиtoken_id.contractaddress: контракт отслеживаемого токена.token_id: идентификатор токена NFT.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, а идентификатор вебхука лежит в data.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 hex-символов. Чтобы проверить в тестовой сети, добавьте заголовок X-Network: testnet в запрос на создание.
Как проверить приёмник до реального депозита?
Заголовок раздела «Как проверить приёмник до реального депозита?»Отправьте пример уведомления на ваш эндпоинт через curl. Тело ниже содержит те же поля, что и настоящее уведомление. Если приёмник записал его в лог и ответил 200, эндпоинт работает. После этого отправьте небольшой перевод в testnet на отслеживаемый адрес, чтобы увидеть настоящее событие.
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}'Что делать с неудавшимися доставками и старыми вебхуками?
Заголовок раздела «Что делать с неудавшимися доставками и старыми вебхуками?»Chaingateway не повторяет неудавшиеся доставки автоматически. GET /api/v2/tron/webhooks/notifications/failed выводит их список, а POST /api/v2/tron/webhooks/notifications/{id}/retry отправляет одну из них повторно. Список ваших вебхуков выводит GET /api/v2/tron/webhooks, изменить вебхук можно через PUT /api/v2/tron/webhooks/{id}, а удалить — через DELETE /api/v2/tron/webhooks/{id}. Удаляйте вебхук, когда он выполнил свою задачу, например после поступления оплаты за заказ.
Важная информация
Заголовок раздела «Важная информация»- Приёмник должен быть общедоступным и принимать HTTP POST-запросы.
- Проверяйте источник и целостность каждого запроса по заголовку
X-Signature. - Сделайте приёмник идемпотентным. По
txidопределяйте уведомление, которое вы уже обработали. - Храните API-токен в хранилище секретов, а не в исходном коде приёмника.
Источники
Заголовок раздела «Источники»- RFC 9110, HTTP Semantics определяет метод POST и коды статуса, которые использует приёмник.
- TRON TRC20 protocol interface определяет события токена, на которых основаны уведомления TRC20.
- Стандарт токенов Ethereum EIP-20 определяет то же для ERC-20 в EVM-сетях.