Webhook или polling: доставка событий и обнаружение пропусков

Заказчик интеграции и технический руководитель выбирают, как получать события заказов: ждать входящий webhook, опрашивать API по расписанию или сочетать оба способа. Результат такого выбора — не название технологии, а согласованная схема доставки, проверки пропусков и восстановления после сбоя.

Ниже — критерии выбора и синтетический пример. Он не относится к клиентской системе Switch On AI и не подтверждает совместимость с конкретным сервисом. Статья также не описывает перенос адреса уже работающего webhook: этому посвящено отдельное руководство.

Какую задачу решает этот процесс

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

Выбор строится вокруг двух независимых задач:

1. Получить новое событие. Webhook передаёт его на входящий endpoint по инициативе источника. При polling интеграция сама обращается к API по расписанию.
2. Проверить полноту. Интеграция сопоставляет полученные идентификаторы с доступной выборкой источника и находит то, чего нет в локальном хранилище.

Webhook может решить первую задачу, но сам по себе не доказывает, что получены все события. Уникальный event_id защищает от повторной обработки известного события, но не обнаруживает отсутствующее. Для поиска пропуска нужен источник контрольной выборки: например, API с cursor или временным watermark.

Официальная документация GitHub описывает общий контраст так: webhook доставляет данные на сервер при наступлении события, а polling периодически обращается к API. Это подтверждает различие push и pull на примере GitHub, но не доказывает правила доставки, повторов или подписи другого провайдера.

Какие данные и правила подготовить

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

К обязательным данным для надёжной схемы относятся уникальный признак события, устойчивое хранилище входных данных и правило дедупликации. Для polling также нужно хранить состояние чтения: cursor либо watermark.

Условные данные зависят от контракта API. Подпись применима, только если источник её предоставляет. cursor нужен при курсорной пагинации; watermark — когда API выбирает записи по времени. Эти механизмы нельзя считать взаимозаменяемыми без документации источника.

До выбора провайдера остаются неизвестными алгоритм и заголовок подписи, срок и порядок повторных доставок, гарантии порядка событий, глубина доступной истории, rate limit, тариф и права API. Их нужно получить из официальной документации и условий конкретного подключения, а не переносить из примера другого сервиса.

Как различаются webhook и периодический опрос

Возьмём одно событие: заказ получил event_id=101.

При webhook источник отправляет HTTP-запрос на доступный endpoint интеграции. Такой push-путь не требует регулярного запроса списка событий, но требует защищённого входящего адреса, проверки запроса и готовности принять доставку в момент обращения источника.

При polling интеграция сама запрашивает события через API. Такой pull-путь не требует входящего endpoint, зато создаёт регулярную нагрузку и зависит от rate limit, доступной истории и способа продолжить выборку. Если период равен P, плановая задержка обнаружения может приближаться к P плюс время ответа и обработки. Это расчётная граница расписания, а не обещание конкретного сервиса.

Запрос «webhook vs polling» поэтому нельзя решать по моде. Webhook подходит, когда источник умеет отправлять нужные события и интеграция может постоянно принимать их. Polling подходит, когда достаточно периодического обновления, входящий endpoint недоступен либо API — единственный документированный способ получить данные. Решение ограничивают требования к задержке, объём событий, доступность обеих сторон и правила API.

Как подтверждать и восстанавливать доставку

Для webhook безопасная последовательность зависит от документации провайдера, но проектное правило можно записать так:

1. Проверить допустимость запроса и подлинность по документированному правилу источника.
2. Атомарно сохранить event_id и полезную нагрузку в устойчивом хранилище.
3. Только после успешного сохранения вернуть предусмотренное провайдером подтверждение.
4. Выполнить бизнес-операцию идемпотентно: повтор с тем же event_id не должен создавать второй результат.

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

Для polling интеграция хранит cursor или watermark. При временной выборке полезно согласовать перекрытие интервалов, потому что событие может появиться в API позже своего времени создания. Перекрытие создаёт повторы, поэтому все страницы проходят дедупликацию по документированному устойчивому идентификатору.

Ключевое различие: повтор — это ещё одна доставка уже известного event_id; пропуск — событие, которое существует в контрольной выборке источника, но отсутствует среди сохранённых событий. Уникальный ключ останавливает повторное исполнение, а сверка обнаруживает пропуск.

Когда использовать гибридную схему

Гибрид объединяет оперативный путь и контроль полноты: webhook передаёт события по мере отправки источником, а polling периодически сверяет локальное хранилище с API. Такая схема полезна, когда задержка важна, но одного факта приёма webhook недостаточно для контроля полноты.

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

Порядок тоже нельзя считать гарантированным без документации. Событие 103 может быть принято раньше 102, а повтор 101 — после обоих. Поэтому интеграция должна опираться на event_id и согласованные правила состояния заказа, а не на предположение, что сеть сохранит порядок отправки.

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

Учебный пример: путь от входных данных до результата

Ниже — полностью синтетический пример. Числа, имена полей, период и ответы API условны; это не клиентский кейс и не результат живого теста.

Исходные данные:

• контрольная выборка API содержит {101, 102, 103};
• webhook-доставки пришли в порядке [101, 101, 103];
• страница запрошена с cursor=c0 и условно вернула события 101–103 вместе с next_cursor=c1;
• период сверки — условные 5 минут;
• локальное хранилище запрещает две записи с одинаковым event_id.

В webhook-потоке три доставки, но только два уникальных события: |{101, 103}| = 2. Значит, повторов 3 − 2 = 1. Относительно API отсутствует |{101, 102, 103} \ {101, 103}| = 1 событие — 102.

cursor двигается отдельно от бизнес-обработки. Интеграция сначала надёжно сохраняет всю страницу 101–103 с дедупликацией, затем фиксирует c1 и продолжает обработку. Если сохранение страницы прервалось, остаётся c0: интеграция запросит страницу повторно, а уникальный ключ остановит дубли. Продвигать cursor до сохранения страницы нельзя — иначе после сбоя часть событий можно пропустить.

Сводная таблица помогает выбрать схему для этого условного процесса:

После сверки сохранено множество {101, 102, 103}. Уникально обработаны три события; доставка 101 повторилась один раз, но не вызвала второе исполнение; пропуск 102 обнаружен только через API.

Как проверить результат перед запуском

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

Перед запуском технический руководитель должен связать подпись с официальной документацией конкретного провайдера, а cursor — с документированным полем ответа API. Секрет подписи выдаёт администратор источника; значение секрета не включают в ТЗ и журналы. Интеграция хранит текущее состояние cursor, но формат и срок его действия задаёт API.

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

Что согласовать для внедрения

Готовый коннектор или инструмент может принять HTTP-запрос, выполнить запрос по расписанию и сохранить состояние. Но он не определит за заказчика, какая задержка допустима, какой event_id устойчив, сколько истории нужно для восстановления и кто разбирает исключения. Эти правила становятся частью собственной интеграции и критериев приёмки.

Перед оценкой работ согласуйте:

• источник событий и доступные API;
• требования к скорости получения и период сверки;
• документированные правила подписи, повторов, пагинации и rate limit;
• хранилище событий и состояния сверки;
• правило дедупликации и разрешённые переходы состояния;
• глубину восстановления после паузы;
• сигнал ошибки и ответственного человека.

Switch On AI может разработать ИИ-помощника, бота или обычную интеграцию для описанной операции после проверки данных и API. В этой задаче ключевым решением, вероятнее всего, будет интеграция: она принимает или запрашивает события, сохраняет их, устраняет повторы и запускает сверку. ИИ-компонент нужен только для отдельной операции, где действительно требуется работа с неструктурированными данными или текстом; он не заменяет контроль доставки.

Условия конкретного продукта — совместимость, тариф, права API и ограничения — проверяются отдельно. Статья не подтверждает выполненное внедрение у упомянутого вендора и не задаёт сроки или гарантированный эффект.

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