Перейти к содержимому

Создание блокчейн-вебхуков для депозитов

Чтобы получать от Chaingateway уведомления о депозитах, нужны принимающий эндпоинт на вашем сервере и вебхук, созданный через POST /api/v2/{chain}/webhooks. Когда транзакция соответствует фильтру вебхука, Chaingateway отправляет на ваш эндпоинт HTTP POST-запрос с данными транзакции. Руководство строит обе части для депозитов TRC20 в TRON. Те же шаги подходят для Ethereum, BNB Smart Chain, Polygon, Arbitrum и Bitcoin. В Solana вебхуков нет.

Сначала прочитайте раздел Как работают вебхуки платежей в блокчейне, если вам нужны основные понятия и формат payload. Для работы нужен API-токен, его описывает Быстрый старт.

Шаги руководства: написать приёмник, сделать его доступным из интернета, создать вебхук, отправить тестовый payload, обработать неудавшиеся доставки 1. Написать приёмник POST-эндпоинт, отвечающий 200 2. Сделать его доступным публичный HTTPS-URL 3. Создать вебхук POST /api/v2/tron/webhooks с url и фильтром 4. Проверить payload'ом curl на ваш собственный приёмник 5. Обработать сбои вывести неудавшиеся уведомления, отправить ихповторно
Шаги 1 и 2 идут до шага 3, потому что URL должен работать к моменту первого события.

Приёмник — это эндпоинт сервера, который принимает 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}`);
});

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"
}'

Ответ приходит со статусом 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-токен в хранилище секретов, а не в исходном коде приёмника.