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

Как работают вебхуки платежей в блокчейне

Вебхук в Chaingateway — это подписка, по которой наши серверы отправляют HTTP-запрос POST на ваш URL, когда транзакция соответствует заданному фильтру, например входящий перевод на один из ваших адресов. Так вы получаете мгновенные уведомления о платежах без опроса. Вебхуки есть для Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON и Bitcoin, но не для Solana.

Жизненный цикл вебхука: создайте вебхук с фильтром, подходящая транзакция запускает POST на ваш URL, ваш сервер отвечает 200, неудавшиеся доставки перечисляются и отправляются повторно по запросу Создайте вебхук POST /api/v2/{chain}/webhooks с url и фильтром Транзакция соответствует фильтру Chaingateway отправляет уведомление POST наваш url Ваш приёмник отвечает 200 и обрабатывает данные Доставка не удалась? GET .../webhooks/notifications/failed, затемPOST .../notifications/{id}/retry
Неудавшиеся уведомления не повторяются автоматически. Вы запрашиваете их список и отправляете повторно сами.

Вы указываете публичный 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 из интернета. Процесс состоит из четырёх шагов:

  1. Создайте приёмный эндпоинт, до которого может добраться Chaingateway.
  2. Создайте вебхук, указывающий на приёмник.
  3. Дождитесь подходящего события в блокчейне.
  4. Прочитайте тело запроса и ответьте 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()

Отправьте запрос 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"
}'

Успешный вызов возвращает статус 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 нет эндпоинтов для вебхуков. Файл OpenAPI определяет их только для Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON и Bitcoin. Для Solana читайте баланс принимающего адреса или список транзакций с фиксированным интервалом и сравнивайте результат с вашими записями.