Магазин должен уведомлять службу доставки о новых заказах, получать статусы отправлений, отправлять данные в CRM, принимать платежи от агрегатора и отдавать события в аналитику. Каждая такая связь — интеграция, и держатся они на двух механизмах: API и вебхуках. Сделаешь их наспех — и получаешь потерянные заказы, дубли оплат и «чёрный ящик», который невозможно отладить при сбое.
В этой статье разберём, как правильно связывать интернет-магазин на 1С-Битрикс со сторонними сервисами: чем API отличается от вебхука, как ловить события через D7, зачем нужны очереди и идемпотентность и как защитить входящие уведомления. Проектирование и поддержку таких связок закрывает наша услуга поддержки API-обменов и webhook-интеграций.
Коротко
- API — вы запрашиваете данные сами (pull); вебхук — сервис уведомляет вас о событии (push). В реальных интеграциях нужны оба.
- Исходящие вебхуки в 1С-Битрикс строят на событиях D7 — штатной точке расширения, срабатывающей при любом изменении данных.
- Отправку выносят в очереди с повторами, а обработку делают идемпотентной — иначе теряются события и появляются дубли.
- Входящие вебхуки защищают подписью, HTTPS и проверкой источника; всё логируют и мониторят.
API и вебхук: в чём разница
Оба механизма связывают системы, но работают в противоположных направлениях. Понимание этой разницы определяет всю архитектуру интеграции.
- API (pull). Инициатор — вы. Магазин сам обращается к сервису и запрашивает данные: «дай статус этого отправления», «дай список тарифов». Данные приходят в ответ на ваш запрос.
- Вебхук (push). Инициатор — сервис. Когда у него происходит событие (платёж прошёл, посылка доставлена), он сам присылает вам уведомление на заранее заданный URL.
API удобно, когда данные нужны по запросу и в удобный вам момент. Вебхук незаменим, когда важна мгновенная реакция на событие: вместо того чтобы постоянно опрашивать сервис «ну что, оплатили?», вы просто ждёте уведомления. На практике интеграция почти всегда использует оба: вебхуки для реакции на события и API для запроса данных и сверки.
Входящие и исходящие интеграции
Второе важное разделение — направление относительно вашего магазина. Оно определяет, кто кого вызывает и что нужно защищать:
| Тип | Кто инициирует | Пример | Что важно |
|---|---|---|---|
| Исходящий вебхук | Магазин → сервис | Новый заказ уходит в CRM | Очереди, повторы, надёжность доставки |
| Входящий вебхук | Сервис → магазин | Платёж от агрегатора | Проверка подписи, идемпотентность |
| Исходящий API-вызов | Магазин → сервис | Запрос тарифов доставки | Таймауты, обработка ошибок |
| Входящий API | Сервис → магазин | Внешняя система тянет заказы | Аутентификация, права доступа |
Для каждого направления — свои требования. Исходящее важно надёжно доставить, входящее — безопасно принять и не обработать дважды. Смешивать эти заботы нельзя: типичная ошибка — защитить входящее, но не позаботиться о надёжной доставке исходящего, и наоборот.
Когда вебхук, а когда опрос
Не всё нужно строить на вебхуках. Иногда надёжнее и проще опрашивать сервис через API по расписанию (polling). Выбор зависит от задачи:
- Вебхук. Когда нужна мгновенная реакция (оплата, смена статуса доставки) и сервис поддерживает уведомления.
- Опрос. Когда вебхуков нет, события редкие, или нужно получать данные пакетами и контролировать нагрузку.
- Комбинация. Вебхук для реакции в реальном времени плюс периодическая сверка через API как страховка от потерянных уведомлений.
Комбинированный подход — самый надёжный для критичных данных вроде оплат. Вебхук даёт скорость, а регулярная сверка через API ловит то, что могло потеряться при сбое сети или недоступности. Полагаться только на вебхуки в критичных сценариях рискованно: одно потерянное уведомление — и заказ повиснет в неправильном статусе.
События D7 как источник вебхуков
Чтобы отправить исходящий вебхук, нужно поймать момент, когда в магазине что-то произошло: создан заказ, изменился его статус, обновился товар. В 1С-Битrix для этого есть штатный механизм — система событий D7. Платформа генерирует события на ключевые действия, а вы вешаете на них свои обработчики.
Это правильная точка расширения по нескольким причинам. Событие срабатывает независимо от источника изменения — пришло оно с сайта, из админки или через обмен с 1С. Вам не нужно менять код компонентов, что делает решение устойчивым к обновлениям платформы. В обработчике события вы формируете данные и инициируете отправку вебхука. Как устроен современный слой событий и работы с данными, мы подробно разбираем в статье про D7 и ORM в 1С-Битрикс, а практику построения безопасных обменов — в материале про безопасность REST и вебхуков.
Очереди и повторные попытки
Самая частая архитектурная ошибка — отправлять исходящий вебхук синхронно прямо в обработчике события. У этого две беды: во-первых, сайт ждёт ответа стороннего сервиса, и пользователь видит задержку; во-вторых, если сервис недоступен, событие теряется навсегда.
Правильная схема — асинхронная отправка через очередь. Обработчик события лишь ставит задачу в очередь и мгновенно отпускает пользователя. Отдельный процесс (агент или очередь) забирает задачи и отправляет вебхуки. Если отправка не удалась, задача возвращается в очередь и повторяется с нарастающими интервалами — так временная недоступность сервиса не приводит к потере данных. Для критичных интеграций это обязательная схема: она отделяет скорость сайта от надёжности доставки и переживает сбои внешних сервисов. Инфраструктурную основу под фоновые процессы и агенты мы разбираем в статье про хостинг и инфраструктуру на BitrixVM.
Идемпотентность обработки
Вебхуки по своей природе могут приходить несколько раз. Сервис повторяет отправку, если не получил подтверждения; сеть может продублировать запрос; сбой вызовет повтор. Если ваш обработчик не готов к этому, повторный вебхук создаст дубль заказа, задвоит оплату или отправит клиенту второе письмо.
Защита — идемпотентность: обработка одного и того же события должна давать один и тот же результат, сколько бы раз оно ни пришло. Достигается это через идентификатор события: каждый вебхук несёт уникальный идентификатор, вы запоминаете обработанные и при повторе просто пропускаете. Так эффект применяется ровно один раз. Идемпотентность обязательна везде, где вебхук меняет состояние: оплаты, заказы, остатки. Игнорировать её — значит однажды получить задвоенные заказы и разбирательства с клиентами.
Безопасность входящих вебхуков
Входящий вебхук — это публичный URL на вашем сайте, который технически может вызвать кто угодно. Без защиты злоумышленник пришлёт поддельное уведомление «заказ оплачен» или «статус изменён», и необорудованный обработчик ему поверит. Поэтому входящие вебхуки защищают несколькими слоями:
- Проверка подписи. Сервис подписывает запрос секретным ключом (обычно HMAC), а вы проверяете подпись — так подтверждается подлинность и целостность.
- HTTPS. Обязательно, чтобы данные и подпись нельзя было перехватить или подменить в пути.
- Проверка источника. Где возможно — ограничение по адресам, с которых сервис шлёт уведомления.
- Валидация содержимого. Обработчик доверяет только корректным подтверждённым данным и не действует по неполным или подозрительным.
Особенно критична проверка подписи для платёжных вебхуков: именно от неё зависит, нельзя ли подделать уведомление об оплате. Это тот случай, когда экономия на безопасности оборачивается прямыми финансовыми потерями.
Штатный REST и свои эндпоинты
Строить интеграции с нуля не обязательно — 1С-Битрикс включает REST-модуль, через который доступны данные и операции магазина, и который умеет создавать вебхуки и приложения. Для многих типовых задач (связка с CRM, сервисами доставки, аналитикой) штатных возможностей достаточно, и это самый быстрый путь.
Когда нужны нестандартные операции или специфическая логика, поверх штатного механизма пишут собственные REST-эндпоинты и обработчики. Разумная стратегия — начинать со штатных возможностей и расширять их только там, где действительно упираетесь в ограничения. Так вы не изобретаете велосипед и получаете поддерживаемое решение. Собственная разработка модулей и эндпоинтов оправдана для сложных интеграций — эту тему мы затрагиваем в статьях про разработку модуля 1С-Битрикс и CI/CD и деплой.
Логирование и мониторинг
Когда интеграций несколько, главная проблема — не построить их, а понимать, что происходит, когда что-то ломается. Без наблюдаемости набор вебхуков превращается в чёрный ящик: заказ не ушёл в CRM, а почему — неизвестно. Поэтому логирование и мониторинг закладывают сразу:
- Лог всех вызовов. Входящие и исходящие запросы с телом, статусом и временем — чтобы видеть, что и куда ушло.
- Хранение идентификаторов. Обработанные события фиксируются для идемпотентности и разбора.
- Мониторинг ошибок. Неудачные доставки и повторы видны, по ним настраиваются оповещения.
- Контракты обмена. Документированные форматы, чтобы при изменениях у сервиса быстро понять, что сломалось.
Наблюдаемость — это разница между «интеграция сломалась, разберёмся за час» и «заказы неделю не уходили в CRM, а мы не знали». Для магазина с живыми деньгами это критично.
Типовые сценарии интеграций
Чтобы теория стала конкретной, вот частые связки и механизмы под них:
- Магазин и CRM. Новый заказ уходит исходящим вебхуком в CRM (событие D7), статусы возвращаются входящим вебхуком.
- Служба доставки. API-запрос тарифов при оформлении, исходящий вызов для создания отправления, входящий вебхук со статусами.
- Платёжный агрегатор. Входящий вебхук об оплате с обязательной проверкой подписи и идемпотентностью.
- Аналитика и маркетинг. Исходящие события о заказах и действиях в системы аналитики.
- Учётная система 1С. Обмен товарами, ценами, остатками и заказами — здесь события D7 связывают сайт с обменом.
Каждый сценарий собирается из тех же кирпичей: события, очереди, идемпотентность, безопасность и логирование. Освоив эти принципы, вы подключаете новый сервис по отработанной схеме, а не изобретаете каждый раз заново.
Частые ошибки
- Синхронная отправка в обработчике. Сайт ждёт сторонний сервис, а при его сбое событие теряется навсегда.
- Нет идемпотентности. Повторный вебхук создаёт дубль заказа или задваивает оплату.
- Входящий вебхук без проверки подписи. Можно подделать уведомление об оплате или статусе.
- Только вебхуки без сверки. Одно потерянное уведомление оставляет заказ в неправильном статусе.
- Правка кода компонентов вместо событий. Решение ломается при обновлении и не ловит изменения из других источников.
- Нет логов и мониторинга. При сбое невозможно понять, что и куда не ушло.
Чек-лист интеграции
- Направления определены. Ясно, где входящие и исходящие вебхуки и API-вызовы, и что для каждого важно.
- Механизм выбран. Для каждого сценария выбраны вебхук, опрос или их комбинация со сверкой.
- События D7 используются. Исходящие вебхуки строятся на штатных событиях, а не на правке компонентов.
- Очереди с повторами. Отправка асинхронная, недоступность сервиса не теряет данные.
- Идемпотентность обеспечена. Повторные вебхуки не создают дублей и задвоений.
- Входящие защищены. Проверка подписи, HTTPS, валидация источника и содержимого.
- Логирование включено. Все вызовы, идентификаторы и ошибки фиксируются и мониторятся.
- Контракты задокументированы. Форматы обмена описаны, изменения у сервисов отслеживаются.
Вывод
Интеграция магазина со сторонними сервисами держится на двух механизмах — API для запроса данных и вебхуках для реакции на события. Надёжность рождается не из самих механизмов, а из дисциплины вокруг них: события D7 как источник, очереди с повторами для доставки, идемпотентность против дублей, подпись и HTTPS для безопасности, логи и мониторинг для наблюдаемости.
Соберите этот фундамент один раз — и подключение каждого нового сервиса превратится в отработанную процедуру, а не в источник потерянных заказов и задвоенных оплат. Начинайте со штатного REST-модуля и событий, расширяйте по мере необходимости и всегда закладывайте надёжность и безопасность с самого начала, а не после первого сбоя.
