← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Вебхуки для крипто-депозитов: как они работают

Как вебхук фиксирует входящий крипто-депозит: вебхук или опрос, поля payload, проверка подписи HMAC и обработка пропущенных уведомлений.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) 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) на один адрес.

Terminal window
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 блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.