Вебхуки или опрос API: как выбрать способ интеграции сайта

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

Задача бизнеса и границы решения

Прежде чем выбирать между вебхуками и опросом API, зафиксируйте, что именно должно происходить при событии. Обычно речь о трёх сценариях: заявка с сайта попадает в CRM, изменение статуса заказа уходит во внешнюю систему, а справочные данные (например, остатки) обновляются на сайте. Для каждого сценария важно понять, кто инициатор обмена и где хранится «истина».

Границы решения описывают так:

• какая система является источником события;
• какая система должна получить событие и что с ним сделать;
• допустимо ли событие потерять или обработать позже;
• кто отвечает за обработку ошибок и разбор спорных случаев.

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

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

Как устроены вебхуки в интеграции сайта

Вебхук — это URL-адрес обработчика, который принимает данные от другой системы при событии. В Битрикс24 есть входящие и исходящие вебхуки с разными ролями.

Входящий вебхук

Входящий вебхук позволяет внешней системе обращаться к REST API Битрикс24 без реализации полного протокола авторизации OAuth 2.0. По документации вы создаёте вебхук в разделе для разработчиков, задаёте понятное название и включаете права (scope) на нужный модуль — например, CRM, если планируете создавать лиды или контакты. После сохранения система формирует URL, в котором уже есть идентификатор пользователя, от имени которого работает вебхук, и секретный код. Остаётся подставить в этот адрес нужный метод REST и передать параметры.

Входящий вебхук нужен, когда сайт должен записать данные в Битрикс24 (создать лид, контакт). Секретный код — это пароль, храните его в защищённом месте.

Исходящий вебхук

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

Важная деталь: в событии часто приходит только идентификатор объекта, а не все его поля. Чтобы получить подробности, обработчик отдельно запрашивает объект через REST. То есть исходящий и входящий вебхуки нередко работают в паре.

Также в Битрикс24 вебхук можно вызывать из роботов CRM: задаёте адрес обработчика и параметры. Это удобно, когда событие привязано к смене стадии сделки.

Опрос API: когда сайт сам спрашивает изменения

Опрос (polling) — регулярные запросы одной системы к API другой для проверки изменений. Инициатор — клиент, а не система-источник.

Чтобы опрос работал предсказуемо, нужны три вещи:

• расписание или интервал обращения;
• признак, по которому отбираются только новые изменения (метка времени, курсор, номер последней обработанной записи);
• правило дедупликации, чтобы одна и та же запись не обрабатывалась дважды.

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

Если же вы только выбираете архитектуру обмена, разумно свериться с общим материалом про API-интеграцию сайта на Битрикс с внешними системами, а затем вернуться к выбору между вебхуком и опросом.

Сравнительная схема: критерии выбора

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

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

Задержки, потери событий и нагрузка

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

Потери событий возможны в обоих вариантах, но причины разные:

• при вебхуке обработчик может быть недоступен в момент вызова, и событие не дойдёт, если не предусмотрена повторная доставка;
• при опросе можно пропустить изменение, если неверно выбран признак отбора или сбился курсор;
• в обоих случаях дубли появляются, если нет правила «одно событие — одна обработка».

Нагрузка тоже различается по природе. Вебхук нагружает систему только в момент событий, но требует, чтобы обработчик выдерживал пики. Опрос создаёт ровный поток запросов, который проще планировать, но он «съедает» ресурсы даже в тишине.

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

Подтверждение обработки и восстановление пропусков

Ключевой вопрос: как вы узнаете, что событие дошло и было обработано. Без ответа на него интеграция остаётся «на честном слове».

Для вебхука стоит предусмотреть:

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

Для опроса стоит предусмотреть:

• хранение последней успешно обработанной позиции (курсора);
• повторный запрос за период, если предыдущий цикл завершился ошибкой;
• сверку итогов: сколько изменений ожидалось и сколько обработано.

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

Практический пример на тестовых данных

Учебный пример. Данные вымышленные, не отражают реальную компанию или процессы.

Входные условия: интернет-магазин на Битрикс принимает заявки с формы, а складская система находится во внешнем контуре. Нужно, чтобы заявки попадали в CRM, а смена статуса сделки уходила на склад.

Действия:

1. Создаём входящий вебхук с правами на CRM, чтобы сайт мог создавать лид или контакт из формы. 2. Настраиваем исходящий вебхук на событие изменения сделки и указываем адрес обработчика. 3. Обработчик записывает входящий вызов в журнал, проверяет служебные параметры и извлекает идентификатор сделки. 4. По идентификатору обработчик через REST запрашивает подробности сделки и передаёт нужные поля на склад. 5. Проверяем: меняем стадию тестовой сделки, смотрим журнал и сверяем переданные поля с тем, что оказалось на складе.

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

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

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

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

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

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

Типичные ошибки и ограничения

Ошибки чаще связаны не с технологией, а с недоописанными правилами.

• Событие считают «доставленным», хотя обработчик его не подтвердил.
• Не различают создание и изменение объекта, из-за чего приходят дубли.
• Хранят секретный код вебхука в общедоступном месте.
• Не проверяют подлинность входящего вызова.
• Выбирают опрос с интервалом, который не соответствует требованиям по задержке.
• Не предусматривают повторную обработку и не ведут журнал.

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

Какие исходные данные подготовить для оценки

Чтобы оценить объём работ, соберите факты о сценарии, а не общие пожелания.

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

Если обмен связан с товарами и заказами, полезно заранее разобраться, как устроена Интеграция Битрикс с 1С: как настроить обмен товарами и заказами — там те же вопросы сопоставления объектов и обработки расхождений.

Собранные данные позволяют сравнить вебхук и опрос по конкретному сценарию, а не абстрактно. Дальше решение принимается по таблице критериев и проверяется на тестовых данных.