Вебхуки для крипто-депозитов: как они работают
Как вебхук фиксирует входящий крипто-депозит: вебхук или опрос, поля payload, проверка подписи HMAC и обработка пропущенных уведомлений.
Проверил(а) Maurice Sobiera
Вебхук — это HTTP-запрос, который сервис отправляет на ваш сервер, когда происходит событие. Для крипто-депозитов событие — это транзакция, которая совпадает с адресом, за которым вы следите. Chaingateway отправляет данные транзакции на ваш endpoint, а ваш код зачисляет средства клиенту. Так заменяется многократный опрос blockchain API на предмет новых транзакций.
Что такое вебхук?
Вебхук — это callback по HTTP. Вы передаёте отправителю URL, и когда наступает заранее заданное событие, отправитель делает POST-запрос на этот URL. Тело запроса — это payload. Думайте об URL как о телефонном номере, по которому отправитель звонит, когда что-то происходит.
Вебхуки и API — два способа обмена данными. С API вы забираете данные: ваш код запрашивает их по расписанию и проверяет, что изменилось. С вебхуком провайдер отправляет данные сам: он связывается с вами в момент события. Push экономит запросы и сокращает задержку. Опрос при этом всё ещё нужен, потому что вебхук лишь сообщает, что что-то произошло. Если нужна полная запись или её нужно проверить, вы запрашиваете API.
Вебхук или опрос: что использовать для депозитов?
Используйте вебхуки, чтобы быстро узнать о депозите, и API, чтобы проверить его и сверить. Вместе они хорошо работают.
| Подход | Сильная сторона | Слабая сторона |
|---|---|---|
| Опрос API | Вы контролируете время и можете продолжить после простоя | Тратит запросы, а задержка равна вашему интервалу |
| Вебхук | Уведомление приходит вскоре после того, как транзакция замечена | Уведомление может потеряться, если ваш endpoint недоступен |
В Chaingateway вебхуки доступны для Bitcoin, Ethereum, BNB Smart Chain, Tron, Polygon и Arbitrum. В Solana вебхуков нет, поэтому там вы запрашиваете транзакции.
Как настроить вебхук на депозит?
Создайте endpoint-получатель, затем зарегистрируйте вебхук для адреса, за которым хотите следить. Endpoint должен быть доступен из публичного интернета. Не нужно открывать IP-адреса Chaingateway, потому что сервис обращается к вашему публичному URL как любой другой клиент.
Вебхуку нужны url и хотя бы один из параметров from или to. Необязательные фильтры: contractaddress, token_id и type, который в Ethereum принимает значения ETH, ERC20 или ERC721. Также можно задать reference длиной до 255 символов, например номер заказа. Этот запрос отслеживает депозиты одного токена ERC-20 (здесь контракт USDT) на один адрес.
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/hooks/deposits", "type": "ERC20", "contractaddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "reference": "order-1042" }'Успешный вызов возвращает статус 201 и ID вебхука в data.webhook. Создайте вебхук до того, как клиент заплатит, чтобы платёж не мог произойти раньше, чем появится наблюдение.
Что содержит уведомление?
Каждый POST содержит поля, которые нужны, чтобы сопоставить платёж с заказом. Этот пример взят из документации Chaingateway для перевода 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}txid определяет транзакцию, а webhook_id говорит, какое наблюдение сработало. Сохраняйте txid с уникальным индексом. Если одно и то же уведомление придёт дважды, второй insert завершится ошибкой, и вы его пропустите.
Как проверить, что уведомление подлинное?
Проверьте заголовок X-Signature до того, как доверять payload. Chaingateway вычисляет HMAC с SHA-256 от txid, используя ваш персональный секрет как ключ, и отправляет результат в кодировке Base64. HMAC определён в RFC 2104. Ваш сервер повторяет вычисление и сравнивает два значения сравнением за постоянное время.
Персональный секрет задаётся в настройках профиля. Как только секрет существует, заголовок добавляется ко всем исходящим вебхукам. В документации по подписи есть код проверки для Python, Java, PHP и JavaScript.
Как выглядит минимальный получатель?
Получатель проверяет подпись, записывает событие один раз и отвечает быстро. Этот пример на Express хранит увиденные ID транзакций в памяти, чтобы оставаться коротким. В продакшне используйте таблицу базы данных с уникальным индексом по txid.
const crypto = require('crypto');const express = require('express');
const app = express();const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => { const { txid, to, amount } = req.body; const expected = crypto .createHmac('sha256', process.env.PERSONAL_SECRET) .update(txid) .digest('base64'); const received = req.get('X-Signature') || '';
const valid = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)); if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) { seen.add(txid); // credit the order that belongs to the address `to` for `amount` } res.sendStatus(200);});
app.listen(3000);Сначала протестируйте получатель в тестовой сети. Передайте заголовок X-Network: testnet при создании вебхука, затем отправьте небольшой тестовый перевод на отслеживаемый адрес. Уведомление должно прийти с txid этого перевода. Документация советует создавать вебхук непосредственно перед платежом, поэтому создавайте его в момент выдачи адреса.
Что будет, если сервер недоступен?
Уведомление автоматически повторно не отправляется. Если ваш endpoint не принимает уведомление, оно появляется в списке неудачных уведомлений по адресу GET /api/v2/{chain}/webhooks/notifications/failed. Новую доставку для каждой записи запускаете через POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Если повтор не удался, запись возвращается в список.
Возвращайте статус успеха, как только сохранили событие, а медленную работу выполняйте позже. RFC 9110 определяет класс кодов состояния 2xx как означающий, что запрос получен и принят. Регулярно проверяйте список неудачных и сверяйте свои записи с API, чтобы пробел не оставался незамеченным. Руководство по гарантиям доставки вебхуков подробнее описывает дубликаты и порядок.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.