Polygon Webhooks: Получайте события в цепочке в реальном времени без опроса

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

Кратко

• Вебхук заменяет опрос: провайдер следит за Polygon и отправляет события (депозиты, переводы, перемещения токенов) на ваш эндпоинт.
• Блоки Polygon появляются примерно каждые 2 секунды, поэтому события приходят быстро, но вам всё равно нужна политика подтверждений перед зачислением средств.
• Обрабатывайте каждую доставку как потенциально дублированную, задержанную или пришедшую не по порядку: проверяйте подпись, сохраняйте ID события и обрабатывайте идемпотентно.
• Быстро подтверждайте получение, выполняйте работу в очереди и регулярно сверяйтесь с цепочкой.
• Вебхуки Chaingateway доставляют HMAC-подписанные, предварительно декодированные события Polygon, поэтому вам не нужно запускать узлы и парсить логи.

Оглавление

• Что такое вебхук Polygon на самом деле
• Почему вебхуки лучше опроса в Polygon
• Подтверждения, финальность и реорги в Polygon PoS
• Как выглядит безопасный обработчик вебхуков Polygon
• Токены и граничные случаи в Polygon
• Сделать самому или использовать унифицированный API
• Наша перспектива: вебхуки — это проблема реестра, а не уведомлений
• Получение вебхуков Polygon с Chaingateway
• Чек-лист запуска
• FAQ
• Источники

Что такое вебхук Polygon на самом деле

Polygon PoS — это EVM-цепочка. Каждый перевод ERC-20, будь то USDC, USDT или токен, выпущенный вами, генерирует лог Transfer. Нативный POL перемещается как обычный перевод значения без логов вовсе. Сырой RPC выдаёт оба вида в разных форматах: логи для токенов, данные транзакций и трассировок для нативных монет. Чтобы узнать, что клиент заплатил, вам нужно собрать эту картину самостоятельно.

Сервис вебхуков делает эту сборку. Вы подписываетесь на адрес (или набор адресов), и когда происходит соответствующее событие, сервис отправляет JSON-полезную нагрузку на ваш URL. Хорошая полезная нагрузка сообщает вам цепочку, хеш транзакции, отправителя, получателя, токен, сумму в удобочитаемых единицах, номер блока и уникальный идентификатор события. В этом разница между «вот лог с hex-топиками» и «клиент 4812 заплатил 250 USDC».

Три вещи, которые люди ищут по этому ключевому слову, на самом деле являются тремя разными инструментами:

• Вебхуки адресов и платежей: уведоми меня, когда средства поступят на эти адреса. Это нужно для платежных потоков.
• Вебхуки событий контрактов: уведоми меня, когда заданный смарт-контракт генерирует заданное событие. Это нужно бэкендам dApp и аналитике.
• Вебхуки уровня протокола: уведомления от самого продукта Polygon об его собственных операциях. Они относятся к документации этого продукта, а не к общему слушателю цепочки.

Эта статья посвящена первому виду, с примечаниями ко второму.

Почему вебхуки лучше опроса в Polygon

Polygon создаёт блок примерно каждые две секунды, согласно этой справке по времени подтверждения. Если вы опрашиваете RPC-эндпоинт за новыми блоками и фильтруете логи самостоятельно, вы сталкиваетесь с компромиссом, у которого нет хорошего решения:

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

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

Подтверждения, финальность и реорги в Polygon PoS

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

Polygon PoS подтверждает быстро. Один трекер указывает, что типичное первое подтверждение занимает от 1 до 5 секунд, и отмечает, что биржи обычно ждут 128 блоков, примерно 4–5 минут, чтобы защититься от реорганизаций. Другой источник сообщает, что обновление Heimdall v2 в июле 2025 года сократило жёсткую финальность до примерно 5 секунд. Практики различаются между биржами и инструментами, а обновления сети меняют цифры, поэтому проверяйте актуальную документацию Polygon перед тем, как зафиксировать порог в продакшене.

Практический способ выбора — привязать политику к риску по стоимости:

Эта таблица — наша рекомендуемая политика, а не правило Polygon. Выбирайте цифры, соответствующие вашей собственной толерантности к риску, и зафиксируйте их.

В вашей модели данных присвойте каждому входящему платежу статус, например detected, confirming и final. Покажите клиенту первое состояние немедленно и перемещайте средства только при последнем. Если ваш провайдер отправляет отдельные события по мере накопления подтверждений, используйте их. Если нет, сохраните номер блока из первого события и сравнивайте его с вершиной цепочки по таймеру.

Как выглядит безопасный обработчик вебхуков Polygon

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

1. Проверьте подпись перед чем-либо ещё

Любой, кто найдёт ваш URL, может отправить на него POST-запрос. Без проверки злоумышленник может отправить фейковое «получено 250 USDC» и уйти с вашим продуктом. Отклоняйте неподписанные или плохо подписанные запросы с кодом 401 и не разбирайте тело дальше.

Chaingateway подписывает запросы с помощью HMAC. Вы вычисляете подпись по необработанному телу запроса с вашим общим секретом и сравниваете её с использованием сравнения в постоянном времени. Используйте необработанные байты, а не повторно сериализованный JSON-объект, потому что повторная сериализация меняет пробелы и порядок ключей и нарушает совпадение. Наш пост о новой функции для усиления безопасности вебхуков подробно объясняет варианты проверки.

Для более широкой картины защиты ключей, эндпоинтов и операционных процессов вокруг цифровых активов этот обзор безопасности и управления рисками цифровых активов — полезное чтение для нетехнической стороны проблемы.

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

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

INSERT INTO processed_events (event_key, received_at)
VALUES ($1, now())
ON CONFLICT (event_key) DO NOTHING;

Если вставка затронула ноль строк, вы уже видели это событие. Верните 200 и остановитесь. Выполняйте вставку и обновление баланса в одной транзакции базы данных, чтобы сбой не мог оставить одно без другого.

3. Подтверждайте быстро, работайте позже

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

4. Не доверяйте порядку

Два события об одном платеже могут прийти в любом порядке, например, обновление подтверждений до первоначального обнаружения. Сравнивайте номера блоков или поля последовательности и игнорируйте всё, что старше состояния, которое вы уже держите. Никогда не позволяйте позднему событию “detected” перезаписать запись “final”.

5. Проверяйте, что утверждает полезная нагрузка

Проверьте, что получатель — это адрес, который вы выдали, что токен-контракт — один из тех, что вы принимаете, и что сумма соответствует инвойсу. Это важнее на Polygon, чем многие ожидают, потому что кто угодно может развернуть токен с названием “USDC” и отправить его на ваш адрес. Сравнивайте адреса контрактов, никогда не символы.

6. Планируйте на случай сбоев

Ваш сервер когда-нибудь будет недоступен. Решите заранее, как вы восстановитесь:

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

Вебхуки — ваш быстрый путь. Сверка — ваша страховка. Запускайте оба.

Токены и граничные случаи на Polygon

USDC и USDT. Платежи стейблкоинами — главная причина, по которой разработчики настраивают вебхуки Polygon, потому что комиссии низкие, а расчет быстрый. Убедитесь, что вы знаете, какой контракт использует каждый стейблкоин на Polygon, и добавьте эти адреса в белый список, как описано выше.

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

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

Неудачные и отмененные транзакции. Отмененная транзакция потребляет газ, но ничего не перемещает. Реагируйте только на события, которые представляют успешные переводы.

Пыль и спам-токены. Нежелательные токены регулярно появляются на адресах. Игнорируйте контракты, которых нет в вашем белом списке.

Создать самостоятельно или использовать унифицированный API

Существует три реалистичных пути к получению уведомлений о событиях Polygon:

1. Запустить собственный ноду и слушатель. Максимальный контроль, но вы отвечаете за обновления ноды, рост хранилища, декодирование логов, обработку реорганизаций и доступность. Разумно, когда инфраструктура блокчейна — это ваш продукт.
2. Использовать ноду или провайдера данных общего назначения и написать фильтрацию самостоятельно. Меньше операционной нагрузки, но вы все равно создаете подписки, повторные попытки, декодирование и слой подписей.
3. Использовать API, ориентированный на платежи, который доставляет декодированные, подписанные события. Вы пишете только эндпоинт и бизнес-логику, больше ничего.

Для команды, которая хочет принимать или отправлять криптовалюту в своем продукте, третий путь обычно быстрее всего приводит к продакшену. Мы подробнее сравниваем варианты в статье Сравнение Blockchain API: 6 типов и когда какой использовать.

Наша перспектива: вебхуки — это проблема бухгалтерии, а не уведомлений

Большинство ошибок интеграции, которые мы видим, не связаны с получением HTTP-запроса. Они касаются того, что происходит после. Команды относятся к вебхуку как к триггеру («платеж поступил, отправляйте»), хотя на самом деле это лишь один из входных данных для бухгалтерии, которая должна оставаться корректной при повторных попытках, реорганизациях и перезапусках.

Это определяет то, как мы строим Chaingateway. Мы доставляем предварительно декодированные события, поэтому ваш код читает сумму и токен, а не hex-кодированные темы логов. Мы подписываем каждый запрос с помощью HMAC, чтобы ваш эндпоинт мог отклонять подделки. И мы охватываем Polygon наряду с Ethereum, Tron, Bitcoin, Solana, BNB Chain и Arbitrum через один REST API, поэтому логика вашего обработчика остается прежней при добавлении второй сети.

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

— Bitblade

Получение вебхуков Polygon с Chaingateway

С Chaingateway Webhooks вы создаёте кошельки или регистрируете адреса через API, подписываетесь на события платежей и получаете подписанные уведомления на ваш эндпоинт. Страница Polygon API охватывает отправку и получение USDC и USDT в Polygon, а Blockchain API — кошельки, переводы, декодированные данные транзакций и оценку газа в поддерживаемых сетях.

Тарифы опубликованы на странице цен:

Платный доступ начинается после бесплатного пробного периода, поэтому вы можете протестировать полный процесс, включая проверку подписей и обработку дубликатов, прежде чем принять обязательства.

Чек-лист запуска

Прежде чем направлять продакшн-трафик на ваш эндпоинт, пройдитесь по этому списку:

• Только HTTPS, с валидным сертификатом.
• Подпись проверяется на сыром теле, сравнение в постоянное время.
• Уникальное ограничение на ключ события.
• 2xx возвращается за пару секунд, работа перемещается в очередь.
• Адреса контрактов в белом списке, суммы и получатели валидируются.
• Модель статуса с состояниями pending и final, и задокументированный порог подтверждений.
• Задача сверки и алерт для пропущенных событий.
• Секреты хранятся вне репозитория и ротируются без даунтайма.
• Тест реплея: отправьте то же событие несколько раз и в случайном порядке в стейджинге.

Источники

• Справочник по времени подтверждений Polygon
• Время подтверждения USDT по сетям
• Документация для разработчиков Polygon

Рекомендуем

• Blockchain Webhooks & Event Notifications
• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• The Use of Webhooks to Process Deposits Automatically