Webhook или опрос API: как выбрать способ обновления

Сначала определите требуемый результат

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

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

Сравнение подходов

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

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

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

Документация Stripe показывает важные свойства событийной доставки: возможны повторы и отсутствие гарантированного порядка. Для другого API эти свойства нужно проверить отдельно. Не используйте пример одной платформы как доказательство контракта всех интеграций.

Разберите повтор и порядок событий

Один и тот же webhook может прийти несколько раз. Храните идентификатор события или другой предусмотренный ключ и обеспечьте идемпотентную обработку. Повтор не должен повторно списывать ресурс или создавать вторую запись.

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

Как организовать опрос

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

Учитывайте пагинацию и изменения во время чтения. Простое увеличение номера страницы иногда приводит к пропуску или повтору записей, если список одновременно меняется. Используйте предусмотренный API механизм последовательного чтения и проверьте его на тестовых данных.

Зачем нужна сверка

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

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

Протокол проверки обмена

• Одно событие обрабатывается повторно без второго эффекта.
• Более старое изменение приходит после нового.
• Источник временно недоступен, затем восстанавливается.
• Обработка прерывается посередине порции.
• Сверка обнаруживает специально пропущенное изменение.
• Журнал позволяет найти операцию без раскрытия секретов.

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

Пример журнала событий и сверки

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

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

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

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

Как восстановить пропущенное webhook-событие

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

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