Как работают вебхуки платежей в блокчейне
Вебхук в Chaingateway — это подписка, по которой наши серверы отправляют HTTP-запрос POST на ваш URL, когда транзакция соответствует заданному фильтру, например входящий перевод на один из ваших адресов. Так вы получаете мгновенные уведомления о платежах без опроса. Вебхуки есть для Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON и Bitcoin, но не для Solana.
Как работает вебхук?
Заголовок раздела «Как работает вебхук?»Вы указываете публичный URL и фильтр, а Chaingateway вызывает URL один раз для каждой подходящей транзакции. Вызов — это HTTP-запрос POST с телом JSON. Ваше приложение читает тело и действует на его основе, например помечает заказ как оплаченный. Для платежей такой механизм называют Instant Payment Notification, или IPN.
Создавайте вебхук незадолго до ожидаемого платежа, с адресом, который его получит. Каждое уведомление содержит приведённые ниже данные. Поле type — это тип актива, здесь перевод токена 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}Что нужно до создания вебхука?
Заголовок раздела «Что нужно до создания вебхука?»Нужен приёмник — эндпоинт на вашем сервере, который принимает запросы POST из интернета. Процесс состоит из четырёх шагов:
- Создайте приёмный эндпоинт, до которого может добраться Chaingateway.
- Создайте вебхук, указывающий на приёмник.
- Дождитесь подходящего события в блокчейне.
- Прочитайте тело запроса и ответьте HTTP-статусом 200.
Приёмник должен быть доступен из интернета. Проверьте файрволы, обратные прокси и сетевые правила, потому что приватный адрес или закрытый порт приведут к сбою каждой доставки. Если вы задали личный секрет, проверяйте подпись каждого запроса, прежде чем доверять ему, как описано в разделе Безопасность вебхуков. Приёмники ниже только читают тело и отвечают.
from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook_receiver(): data = request.get_json() # Process the webhook data # Update database, trigger notifications, execute business logic, etc. return 'Webhook received successfully', 200
if __name__ == '__main__': app.run()const express = require('express');
const app = express();app.use(express.json());
app.post('/webhook', (req, res) => { const data = req.body; // Process the webhook data // Update database, trigger notifications, execute business logic, etc. res.status(200).send('Webhook received successfully');});
app.listen(3000, () => { console.log('Webhook receiver is listening on port 3000');});<?php
$data = file_get_contents('php://input');$payload = json_decode($data, true);
// Process the webhook data// Update database, trigger notifications, execute business logic, etc.
http_response_code(200);echo 'Webhook received successfully';<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ /* * Register a route for it, for example: * Route::post('/webhook', [WebhookController::class, 'handle']); */ public function handle(Request $request) { $payload = $request->all();
// Process the webhook payload \Log::info('Webhook received: ', $payload);
return response()->json(['status' => 'success']); }}Как создать вебхук?
Заголовок раздела «Как создать вебхук?»Отправьте запрос POST на /api/v2/{chain}/webhooks. В теле нужны url вашего приёмника и фильтр. Поля фильтра приведены ниже.
| Поле | Значение |
|---|---|
url | Обязательное. Полный URL вашего приёмника, включая путь. |
from | Адрес отправителя, за которым нужно следить. |
to | Адрес получателя, за которым нужно следить. |
contractaddress | Адрес контракта токена, который нужно отслеживать. Недоступно в Bitcoin. |
token_id | Идентификатор токена NFT. |
type | Тип актива. Ethereum и Arbitrum: ETH, ERC20, ERC721. Polygon: MATIC, ERC20, ERC721. BNB Smart Chain: BNB, BEP20, BEP721. TRON: TRX, TRC10, TRC20, TRC721. |
reference | Ваша собственная метка, до 255 символов. |
Укажите from или to. Если не указать ни одного, API требует contractaddress и token_id. Вебхуки Bitcoin принимают только url, from и to. Форматы адресов проверяются, а несоответствующий адрес возвращает статус 422 с именем поля в errors.
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/webhooks \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/webhook", "contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7", "type": "ERC20", "reference": "order-1042"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/webhooks"
payload = { "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/webhook", "contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7", "type": "ERC20", "reference": "order-1042"}headers = { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/webhooks', headers: {'Content-Type': 'application/json', Authorization: 'Bearer YOUR_API_TOKEN'}, data: { to: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', url: 'https://example.com/webhook', contractaddress: '0xdac17f958d2ee523a2206206994597c13d831ec7', type: 'ERC20', reference: 'order-1042' }};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/webhooks', [ 'json' => [ 'to' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', 'url' => 'https://example.com/webhook', 'contractaddress' => '0xdac17f958d2ee523a2206206994597c13d831ec7', 'type' => 'ERC20', 'reference' => 'order-1042', ], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', ],]);
echo $response->getBody();Успешный вызов возвращает статус 201 и идентификатор вебхука:
{ "status": 201, "ok": true, "message": "Webhook created", "data": { "webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46" }}Существующими вебхуками вы управляете так: GET /api/v2/{chain}/webhooks возвращает список, GET .../webhooks/{id} читает один вебхук, PUT .../webhooks/{id} изменяет его, а DELETE .../webhooks/{id} удаляет. Удаляйте вебхук, когда платёж пришёл, чтобы он не срабатывал на последующие переводы. PUT отвечает статусом 404 и сообщением Webhook not found, если такого идентификатора нет.
Что происходит, если доставка не удалась?
Заголовок раздела «Что происходит, если доставка не удалась?»Chaingateway не повторяет неудавшуюся доставку самостоятельно. Неудавшиеся уведомления сохраняются, и вы сами читаете их и отправляете повторно. Для этого есть два эндпоинта: GET /api/v2/{chain}/webhooks/notifications/failed и POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Список разбит на страницы параметром запроса page.
Каждая запись показывает txid, целевой url, сохранённый response вашего сервера и число attempts. После запуска повтора уведомление исчезает из списка неудавшихся. Если повтор тоже не удался, оно возвращается в список. GET /api/v2/{chain}/webhooks/notifications возвращает все уведомления, включая успешные. Запустите небольшое задание, которое с интервалом проверяет список неудавшихся и повторяет то, что в нём есть, и сделайте приёмник идемпотентным, используя txid как ключ, чтобы повторное уведомление не причинило вреда.
Как обнаруживать депозиты в Solana?
Заголовок раздела «Как обнаруживать депозиты в Solana?»У Solana нет эндпоинтов для вебхуков. Файл OpenAPI определяет их только для Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON и Bitcoin. Для Solana читайте баланс принимающего адреса или список транзакций с фиксированным интервалом и сравнивайте результат с вашими записями.
Источники
Заголовок раздела «Источники»- RFC 9110, HTTP Semantics определяет метод POST и коды статуса 2xx, которыми отвечает приёмник.
- Ethereum transactions описывает поля транзакции, которые появляются в уведомлениях в сетях EVM.
- Документация по транзакциям TRON описывает типы транзакций, на которых основаны значения
typeв TRON.