Самая частая интеграция, которую мы видим в логах, выглядит так: клиент создаёт заказ и начинает опрашивать его статус в цикле, раз в секунду, пока не появится код. Это работает, но платит за это вся система — и клиент первым.

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

Вебхук переворачивает схему: вы указываете адрес обработчика, и мы сами отправляем POST-запрос ровно в момент, когда сообщение разобрано. Никакого цикла, никакого ожидания следующей итерации, средняя задержка падает до сотен миллисекунд. Обработчик получает идентификатор заказа, номер, код и полный текст сообщения.

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

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

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