Вебхуки криптоплатежей: как они работают и как их создать

Криптоплатёжный вебхук — это HTTP-запрос, который блокчейн-сервис отправляет на ваш сервер, когда в сети что-то происходит, например когда на адрес клиента приходит депозит. Вместо того чтобы каждые несколько секунд спрашивать сеть, поступил ли платёж, вы передаёте провайдеру URL, и он вызывает вас сам.

Чтобы работать с этим в продакшене, нужны четыре вещи: публичная конечная точка, проверка подписи, идемпотентная обработка дубликатов событий и запасной способ для пропущенных доставок. В этом руководстве разобрана каждая из них.

Коротко

• Вебхук передаёт событие на ваш сервер, когда происходит платёж или событие кошелька. Так вы отказываетесь от постоянного опроса и нагрузки, которую он создаёт.
• Проверяйте подпись каждого запроса, прежде чем доверять любому полю в нём. В Chaingateway подпись покрывает только ID транзакции, поэтому сумму и получателя проверяйте сами.
• Отвечайте кодом 2xx быстро, а основную работу выполняйте в фоновом задании.
• Считайте каждое событие потенциально повторным: сохраняйте ID событий и делайте обновления заказов идемпотентными.
• Держите медленное задание сверки для ожидающих платежей. Chaingateway не повторяет неудачные уведомления сам, поэтому пропущенная доставка иначе оставит заказ зависшим.

Что такое криптоплатёжные вебхуки?

Вебхук — это обратный вызов. Вы регистрируете URL и сообщаете провайдеру, какие события вас интересуют. Когда событие происходит, провайдер отправляет POST-запрос с JSON-телом, которое его описывает. Для криптоплатежей такими событиями обычно являются входящий перевод на отслеживаемый адрес, исходящий перевод или перевод токена по контракту.

Альтернатива — поллинг. Ваш сервер по таймеру вызывает API и сравнивает результат с тем, что видел в прошлый раз. Поллинг просто написать, но он расточителен в работе. Каждый запрос, который ничего нового не возвращает, стоит вам лимита запросов, вычислений и задержки. Задержка между платежом и вашей реакцией равна вашему интервалу. При нескольких сетях и тысячах адресов клиентов число вызовов быстро растёт.

Вебхуки меняют направление. Провайдер следит за сетью, сопоставляет транзакции с адресами, на которые вы подписались, и уведомляет вас один раз. Время реакции сокращается до секунд, а ваша инфраструктура простаивает, пока не появится работа. Более подробный довод в пользу депозитов изложен в статье как вебхуки обрабатывают депозиты автоматически.

Вебхуки и поллинг в сравнении

Последняя строка — практический ответ. Основным сигналом должны быть вебхуки, а поллинг — медленной страховкой, которая проверяет только ещё ожидающие платежи. Проверяйте только счета, которые всё ещё ожидают оплаты. Тогда пропущенная доставка находится за несколько минут, а число запросов остаётся низким.

Как вебхук обнаруживает криптоплатёж?

Сторона провайдера скрыта от вас, но её устройство объясняет большую часть поведения, с которым вы столкнётесь при тестировании.

1. Подписка. Вы создаёте кошелёк или регистрируете адрес, затем регистрируете для него вебхук через API провайдера. Подписка содержит ваш URL обратного вызова и фильтры, например отправителя, получателя, адрес контракта и тип транзакции.
2. Мониторинг. Провайдер держит ноды для каждой поддерживаемой сети и читает каждый новый блок. Каждая транзакция сопоставляется с подписками, а для токенов — с логами переводов контракта.
3. Декодирование. Сырые данные сети неудобны для чтения. Перевод токена в Ethereum — это закодированная запись лога, а у Bitcoin есть входы и выходы, а не отправитель и получатель. Провайдер превращает это в читаемую полезную нагрузку.
4. Доставка. Провайдер отправляет полезную нагрузку на ваш URL. Если ваш сервер не отвечает кодом успеха, дальнейшее зависит от провайдера. Одни повторяют отправку по расписанию. Chaingateway сам не повторяет: он выводит список неудачных уведомлений, и вы запрашиваете повторную отправку каждого из них.

Уведомление Chaingateway содержит поля id, webhook_id, from, to, blocknumber, datetime, type, contractaddress, tokenid, txid и amount. Те же имена полей используются в Ethereum, BNB Smart Chain, Polygon, Arbitrum и Tron. Вебхуки Bitcoin фильтруют только по отправителю и получателю. У Solana вебхуков нет. Поддерживаются стандарты токенов ERC-20, BEP-20 и TRC-20. Это важно, потому что большинство реальных платежей — это переводы стейблкоинов, а не нативной монеты.

События, на которые стоит подписаться

Начинайте узко. В Chaingateway вебхук задаётся фильтрами, поэтому каждый тип события соответствует комбинации фильтров:

• Входящий перевод на депозитный адрес клиента использует to. Это основное событие для зачисления на счёт или отметки счёта как оплаченного.
• Исходящий перевод использует from, например чтобы видеть, когда выплата или вывод средств попадает в сеть.
• Перевод токена использует type (например, ERC20 или TRC20) вместе с contractaddress.
• Перевод NFT использует поле token_id с типом ERC721 или TRC721.
• Необязательное поле reference длиной до 255 символов позволяет связать вебхук с заказом или клиентом в вашей системе.

Уведомление сообщает, что транзакция, подходящая под фильтр, замечена. Считать ли её окончательной, решаете вы сами по своей политике, как объясняет раздел о глубине подтверждения.

Наша статья о вебхуках Polygon без поллинга показывает, как это выглядит в одной сети.

Как настроить и обработать конечную точку вебхука?

Конечная точка — это обычный маршрут HTTPS на вашем сервере. Разница между демонстрационным и продакшен-обработчиком заключается в нескольких привычках.

Требования к конечной точке

URL должен быть доступен из публичного интернета по HTTPS. Адреса localhost и приватные сети не могут принимать вызовы, поэтому в разработке понадобится туннель, который открывает ваш локальный порт. Держите маршрут выделенным под вебхуки, принимайте только POST и не ставьте его за экраны входа или middleware CSRF, которое отклонит запрос от машины.

Обработчик должен отвечать быстро. Общая рекомендация, например в документации Stripe по вебхукам, — быстро вернуть код успеха, до любой сложной логики, которая может превысить таймаут. Успешным считается статус 2xx по RFC 9110. То же правило относится и к криптособытиям. Если вы обновляете базу данных, отправляете письмо и вызываете систему учёта до ответа, медленный внешний сервис может заставить провайдера считать доставку неудачной.

Надёжный шаблон выглядит так:

1. Прочитайте тело запроса.
2. Проверьте подпись.
3. Запишите событие с его ID в очередь или таблицу событий.
4. Верните 200.
5. Пусть воркер обработает событие из очереди.

Как проверять подписи вебхуков?

Любой, кто найдёт ваш URL, может отправить на него JSON. Если ваш обработчик зачисляет деньги на счёт, потому что запрос говорит, что депозит пришёл, поддельный запрос — это кража. Проверка подписи закрывает эту дверь.

Типичная схема — HMAC, описанный в RFC 2104. Провайдер вычисляет хеш с ключом, секретом, который знают только он и вы, и передаёт результат в заголовке. Вы пересчитываете хеш и сравниваете. Три детали часто подводят:

• Знайте, что подписано. Многие провайдеры подписывают всё тело запроса, поэтому проверять нужно по исходным байтам, а не по повторно сериализованному JSON. Chaingateway подписывает только ID транзакции.
• Сравнивайте за постоянное время. Используйте функцию безопасного сравнения вашего языка, а не простую проверку на равенство.
• Проверяйте временную метку, если схема её предусматривает. Отклонение старых меток ограничивает повторное воспроизведение перехваченного запроса. У схемы Chaingateway временной метки нет, поэтому дедуплицируйте по ID транзакции.

Chaingateway отправляет подпись в заголовке X-Signature, когда вы задали личный секрет в профиле. Значение — это HMAC-SHA256 поля txid в кодировке Base64, вычисленный с этим секретом. В руководстве по проверке подписи есть рабочий обработчик на Node.js, а в документации — версии на Python, Java и PHP. Поскольку подписан только txid, действительная подпись не доказывает, что amount или to не изменены. Сверьте их со счётом или с сетью, прежде чем что-либо зачислять.

Храните секрет в переменной окружения или менеджере секретов, а не в репозитории, и выпустите новый, если он когда-либо попадёт в лог. Новый секрет вступает в силу сразу.

Как обрабатывать повторы, дубликаты и медленные подтверждения?

Сети выходят из строя, а при развёртываниях серверы перезапускаются. Ваш обработчик рано или поздно получит одно и то же событие дважды, например после повторной отправки, а иногда и события не по порядку. Закладывайте это в дизайн с самого начала.

Сделайте обработку идемпотентной

Каждое событие несёт что-то, что его идентифицирует. В уведомлении Chaingateway это txid вместе с webhook_id. Сохраните этот идентификатор с уникальным ограничением, прежде чем действовать. Если вставка не прошла, потому что ключ уже существует, вы это событие видели и можете вернуть 200, ничего не делая.

Затем сделайте саму бизнес-операцию безопасной для повтора. «Пометить счёт 1042 как оплаченный транзакцией X» — идемпотентно. «Прибавить 50 к балансу» — нет. Предпочитайте первую форму или привяжите изменение баланса к уникальной записи события в одной транзакции базы данных.

Учитывайте глубину подтверждения

Транзакция, попавшая в блок, — это не то же самое, что платёж, под который можно отправить товар. Сети различаются по тому, как быстро блок становится маловероятным к откату, и правильный порог зависит от суммы и актива. Задайте политику для каждой сети и размера заказа и храните состояние каждого платежа: обнаружен, подтверждается, подтверждён, неуспешен. Вебхук, который сообщает об обнаружении, должен переводить заказ в состояние «платёж замечен», а не «выполнен».

Недоплаты, переплаты и неверные токены

Клиенты отправляют не ту сумму чаще, чем кто-либо ожидает. Ваш обработчик должен сравнить полученную сумму и актив со счётом и разветвиться: точное совпадение, недоплата, переплата или неожиданный токен. Заранее решите, зачисляете ли вы разницу автоматически, держите ли на проверке или возвращаете деньги. Декодированная полезная нагрузка с активом и суммой в отдельных полях превращает это сравнение в несколько строк кода, а не в задачу разбора данных.

Держите страховочную сеть

Доставка может не пройти, а Chaingateway её не повторяет. Неудачные уведомления показываются в GET /api/v2/<chain>/webhooks/notifications/failed, и каждое вы отправляете заново через POST /api/v2/<chain>/webhooks/notifications/{id}/retry. Запустите задание по расписанию, каждые несколько минут, которое проверяет этот список и смотрит счета, всё ещё ожидающие дольше разумного срока. Когда оно находит платёж, о котором ваш вебхук не сообщил, оно пропускает его через тот же путь обработки. Один путь кода для обоих источников означает один набор ошибок.

Как тестировать и мониторить конечную точку вебхука?

Наращивайте уверенность по слоям:

1. Локальный тест. Напишите небольшой скрипт, который подписывает пример полезной нагрузки вашим тестовым секретом и отправляет его на вашу конечную точку. Убедитесь, что действительная подпись проходит, а изменённый txid отклоняется.
2. Запуск в тестовой сети. Создайте кошелёк в тестовой сети с заголовком X-Network: testnet, зарегистрируйте вебхук и отправьте небольшой перевод из фаусета. Вы увидите реальную последовательность событий, включая задержку до уведомления, которой не научит ни один пример полезной нагрузки.
3. Проверка дубликатов. Отправьте одно и то же действительное событие пять раз. Счёт должен измениться один раз, а в логах должны быть видны четыре пропущенных дубликата.
4. Проверка сбоя. Намеренно заставьте обработчик вернуть 500. Затем найдите уведомление в списке неудачных, восстановите обработчик и отправьте уведомление заново. Оно должно обработаться один раз.

После запуска в работу записывайте ID каждого входящего события, результат проверки, итог обработки и затраченное время. Настройте оповещения на три вещи: сбои проверки подписи (неверный секрет или атакующий), растущую очередь (воркеры отстают) и счета, которые ожидают значительно дольше обычного (тихие проблемы с доставкой).

Частые проблемы и их обычные причины:

Как начать получать события платежей с Chaingateway?

Вебхук создаётся одним запросом к POST /api/v2/<chain>/webhooks. В примере регистрируется наблюдатель депозитов TRC20 со ссылкой на ваш заказ:

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "TWrTTVizHkF3LxTiWE9vCnhWC7CBpNXe22",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "type": "TRC20",
    "url": "https://shop.example.com/hooks/crypto",
    "reference": "order-10442"
  }'

Вебхуки Chaingateway работают вместе с блокчейн-API, поэтому событие, которое сообщает о поступлении депозита, и вызов, который передаёт его дальше, находятся под одним аккаунтом.

Тарифы опубликованы на странице цен: Plus стоит 49 € в месяц, Pro — 99 €, Premium — 249 € и Enterprise — 499 €, либо 490 €, 990 €, 2 490 € и 4 990 € в год при годовой оплате. Бесплатный пробный период на 7 дней не требует карты и KYC, поэтому сначала можно подключить конечную точку и пройти проверки из раздела выше.

Часто задаваемые вопросы

Нужен ли мне поллинг, если я использую вебхуки?

Да, но лишь в небольшом объёме. Используйте вебхуки как основной сигнал и запускайте по расписанию проверку ещё ожидающих платежей, чтобы недоставленное событие не оставило заказ зависшим. Проверка должна пропускать найденные платежи через тот же код обработки, что и события вебхуков.

Как понять, что вебхук действительно пришёл от моего провайдера?

Проверьте заголовок подписи вашим общим секретом и отклоняйте запросы, которые не прошли проверку. В Chaingateway это заголовок X-Signature, HMAC от txid и личный секрет, который вы задаёте в профиле. Никогда не доверяйте содержимому неподписанного запроса, даже если URL секретный.

Что должна возвращать моя конечная точка?

Возвращайте статус 2xx, как только проверили и сохранили событие. Медленную работу, например письма, обновления бухгалтерии и вызовы сторонних сервисов, выполняйте в фоновом воркере. Медленный или неудачный ответ отправляет уведомление в список неудачных, а повторная отправка доставляет его во второй раз.

Может ли одна настройка вебхука покрывать несколько блокчейнов?

Может, если провайдер приводит данные к единому виду. Chaingateway использует одни и те же поля уведомлений в Ethereum, BNB Smart Chain, Polygon, Arbitrum и Tron, поэтому один обработчик может обрабатывать события из всех этих сетей, а правила подтверждения для каждой сети задаются в вашей логике. Вебхуки Bitcoin фильтруют только по отправителю и получателю, а у Solana вебхуков нет.

Источники

• Webhooks, документация Stripe
• HMAC: Keyed-Hashing for Message Authentication, RFC 2104
• Successful 2xx status codes, HTTP Semantics, RFC 9110

Рекомендуем

• Использование вебхуков для автоматической обработки депозитов
• Вебхуки и WebSockets для разработчиков: шаблон ingest, queue, fan out
• Вебхуки Polygon: события блокчейна в реальном времени без поллинга
• Оповещения о криптовалюте в реальном времени: приложения с ценами и вебхук-оповещения