Вебхук подходит, когда система умеет надёжно сообщать о нужном событии. Опрос API нужен, когда событий нет, они неполные или требуется регулярная сверка состояния. Для важных интеграций часто лучше гибрид: webhook даёт быстрый запуск, а плановый опрос находит пропуски и расхождения.
Выбор нельзя делать только по желаемой скорости. Нужно учесть лимиты API, гарантию доставки, порядок событий, объём данных и возможность восстановить период после сбоя.
Как работают три режима
Webhook. Источник отправляет HTTP-запрос при событии: создан заказ, изменена сделка, получено сообщение. Получатель быстро подтверждает приём и обрабатывает событие сразу или через очередь.
Polling. Интеграция по расписанию спрашивает API: «Что изменилось после этой отметки или ID?» Подход зависит от корректного курсора, сортировки и сохранения последней обработанной позиции.
Гибрид. Webhook запускает быструю обработку, а периодическая сверка сравнивает источник и получателя. Если webhook потерялся или был неверно обработан, сверка создаёт операцию восстановления.
Сравнение вебхуков и polling
| Критерий | Webhook | Опрос API | Гибрид |
|---|---|---|---|
| Задержка | Обычно минимальная | Равна интервалу опроса и времени выборки | Быстро в норме, сверка позже |
| Нагрузка | Зависит от числа событий | Есть даже когда изменений нет | События плюс редкая контрольная выборка |
| Потеря события | Нужны retry отправителя и очередь получателя | Можно забрать изменение позже по курсору | Пропуск webhook находит сверка |
| Порядок | События могут прийти повторно или не по порядку | Определяется сортировкой и курсором API | Нужна единая модель состояния |
| Восстановление периода | Сложно без архива событий или повторной отправки | Возможно, если API позволяет выбрать период | Предусмотрено плановой сверкой |
Когда выбирать webhook
Webhook хорош для действий, где важна быстрая реакция: новая заявка, сообщение, платёж, смена статуса. Проверьте, какие события реально доступны, что входит в payload и повторяет ли поставщик доставку при ответе 5xx или таймауте.
Обработчик должен быстро вернуть подтверждение. Тяжёлую работу лучше положить в очередь, иначе отправитель решит, что доставка не состоялась, и пошлёт событие снова. Каждый запрос получает идентификатор и проходит проверку подлинности. Повтор того же события не создаёт второй объект.
Официальная документация amoCRM по чатам, например, описывает отдельные webhook-события и их структуры. Список поддерживаемых событий меняется, поэтому его фиксируют для конкретной версии интеграции. Webhooks API чатов amoCRM.
Когда нужен опрос API
Polling выбирают, если источник не отправляет событие, payload webhook не содержит нужных данных или требуется получить итоговое состояние. Например, сервис может сообщить «заказ изменён», но детали всё равно нужно запросить по API.
Нельзя каждый раз выгружать все записи. Нужны курсор, фильтр по времени изменения или стабильная последовательность ID. Сохраняйте небольшой перекрывающий интервал, потому что часы систем и время фиксации могут отличаться. Повторно выбранные записи отсекаются по идентификатору и версии.
Опрос должен учитывать лимиты. Документация amoCRM указывает 7 запросов в секунду на интеграцию и до 50 на аккаунт; некоторые методы ограничивают размер страницы. Частый полный обход способен создать 429 и повлиять на соседние интеграции. Официальные ограничения API amoCRM.
Почему критичным процессам полезна сверка
Даже при надёжных webhook события могут быть пропущены из-за неверной настройки, истёкшего токена, сбоя DNS или ошибки вашего обработчика. Если интеграция создаёт заказы и передаёт оплаты, одного канала доставки недостаточно.
Плановая сверка отвечает на бизнес-вопрос: все ли заказы за период имеют связанный объект и ожидаемый статус с другой стороны? Она работает реже основного потока и не обязательно повторяет всю интеграцию. Её задача — найти расхождение и создать понятную операцию восстановления.
Сверка должна иметь ограничение периода и результат: число проверенных, найденных расхождений, исправленных автоматически и оставленных человеку. Иначе она превращается в ещё один бесконечный импорт.
Дерево выбора
- Есть ли у источника событие для нужного бизнес-изменения? Если нет — polling.
- Достаточно ли данных в событии? Если нет — webhook запускает запрос деталей.
- Гарантирует ли поставщик повтор доставки и можно ли запросить историю? Если нет — добавьте собственную очередь и сверку.
- Критична ли задержка? Если нет, плановый опрос может быть проще и надёжнее.
- Можно ли выбрать изменения по стабильному курсору? Если нет, согласуйте окно и дедупликацию.
- Как восстановить сутки после простоя? Если ответа нет — архитектура не готова к запуску.
Что проверить на приёмке
- обычное событие и измеренная задержка до результата;
- повтор одного webhook;
- два события одного объекта в обратном порядке;
- ответ обработчика 500 и последующая повторная доставка;
- остановка интеграции на час и восстановление пропущенного периода;
- граница страницы polling и одинаковое время изменения у нескольких записей;
- ограничение API и ответ 429;
- сверка, которая находит специально созданное расхождение.
Логируйте не только ошибки. Полезны время последнего входящего события, время последнего успешного polling, отставание курсора и число операций в очереди. Нулевая ошибка при нулевом потоке — не доказательство здоровья.
Как записать решение в ТЗ
Укажите основной режим, резервный механизм и окно восстановления. Пример: «Оплата поступает по webhook; обработчик подтверждает приём после записи в очередь; повтор отсекается по payment_id; каждые два часа сервис сверяет платежи за последние три часа с перекрытием; расхождения старше 15 минут создают алерт».
Такой текст можно принять и передать другому специалисту. Если нужна помощь с самим контрактом, используйте материал про ТЗ на API-интеграцию или закажите разработку с контролируемым сервисным слоем.