Партнёр amoCRM · Бизнес-партнёр 1С-Битрикс · по всей России

Запись № 045 · Разработка · Внедрение

Вебхук в Битрикс24: входящий и исходящий — как работает и как подключить

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

6 минут чтения Лаборатория внедрений
Вебхук встаёт под нагрузкой. Обложка записи «Вебхук в Битрикс24: входящий и исходящий — как работает и как подключить»

Что такое вебхук в Битрикс24 и какие задачи он закрывает

Собственник хочет связать портал с телефонией, сайтом и сквозной аналитикой: чтобы звонок попадал в карточку, заявка с сайта создавала сделку, а в отчётах было видно, откуда пришёл клиент. Для этого не всегда нужно заказывать отдельное приложение — в Битрикс24 есть штатный механизм обмена данными по секретному URL. Это и есть вебхук.

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

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

Как работает входящий вебхук

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

Экран настройки пользовательских полей Битрикс24: поле «ID заявки на сайте», добавленное для хранения идентификатора из внешней формы.
Входящий вебхук заполняет поле при создании сделки — так источник заявки сохраняется в карточке.

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

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

Часть методов вебхуку недоступна — те, которым нужен контекст приложения: размещение виджетов в интерфейсе, часть методов телефонии и чат-ботов. Если задача упирается в такой метод, штатный путь — приложение, вебхук его не выполнит. Механику подключения телефонии мы разбирали отдельно: телефония в Битрикс24 и звонок в сделке.

Полное описание методов и ограничений есть в документации Битрикс24 по вебхукам.

Как работает исходящий вебхук

Исходящий вебхук работает наоборот: при наступлении события портал сам шлёт POST-запрос на ваш URL. Формат — application/x-www-form-urlencoded, в запросе приходят поля event (имя события), data (данные объекта), ts (метка времени) и auth (данные авторизации).

Карточка сделки Битрикс24: поле «Сумма и валюта» пустое; такие поля не передаются в теле исходящего события — только идентификатор объекта.
Исходящий вебхук передаёт только ID сделки — за суммой и остальными полями обработчик идёт отдельным запросом.

Здесь есть нюанс, из-за которого обмен часто собирают неверно. События CRM обычно передают только идентификатор объекта — например, ID сделки. Самих полей сделки в запросе нет. Чтобы получить сумму, стадию и контакт, обработчик делает дополнительный вызов REST-метода по этому ID. Одно событие превращается в два-три обращения к порталу — дальше увидим, чем это оборачивается под нагрузкой.

URL-обработчик обязан быть публично доступен из внешней сети. Localhost, адреса внутри приватной сети и самоподписанные SSL-сертификаты портал не примет — запрос не дойдёт.

Поле auth[application_token] — то, по чему обработчик понимает, что запрос пришёл от вашего портала. В настройках вебхука показан токен; обработчик сверяет значение из запроса с этим токеном и, если они не совпадают, отклоняет запрос как недоверенный. Токен статичен и одинаков для каждого события, поэтому на своей стороне обработчику стоит сверять метку времени ts и отклонять запросы со старой меткой (типичное окно — 300 секунд), а повторные события с тем же идентификатором — не обрабатывать дважды. Так один и тот же запрос не пройдёт по второму разу.

Где интеграция на вебхуках начинает ломаться

REST API Битрикс24 ограничивает частоту запросов по принципу leaky bucket, «дырявого ведра»: на большинстве порталов порог блокировки — 50 запросов при сливе 2 запроса в секунду, на старших планах — 250 при сливе 5 в секунду. Когда порог превышен, портал возвращает HTTP 503 с кодом QUERY_LIMIT_EXCEEDED, и часть запросов отбивается.

Экран настройки полей сделки Битрикс24: пользовательские поля для аналитики — «ClientID Метрики», «yclid», «roistat_visit».
Когда вебхук упирается в лимит, поля аналитики не заполняются и источник сделки теряется в отчётах.

Лимит считается по IP-адресу источника. Если на одном сервере несколько вебхуков или сервисов работают с одним порталом, они делят общую частоту и под нагрузкой гасят друг друга. Добавьте сюда дополнительные вызовы за полными данными по каждому событию — и на пиковом потоке сделок обмен упирается в лимит. Часть событий не обрабатывается: звонок или заявка не попадают в карточку, источник сделки в сквозной аналитике остаётся пустым.

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

Если нужно понять, какие события и объёмы обмена уже идут через портал и где он упирается в потолок, это видно на аудите портала Битрикс24.

Когда вебхука достаточно, а когда задачу стоит строить как приложение

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

Стабильный поток сделок, работа на нескольких порталах и управляемые права — это уже про приложение. Оно не зависит от прав одного сотрудника, переносится между порталами и имеет собственный контекст для методов, недоступных вебхуку (виджеты, телефония, чат-боты). Собственный контекст снимает и часть историй с лимитами, потому что обмен можно строить пакетами и очередями, не упираясь в один IP.

Наш порядок работы такой. На аудите мы смотрим, какие события нужны, какой объём обмена и где уже теряются данные, и собираем интеграцию на коде или штатными средствами платформы. No-code-склейки вроде Zapier или Make годятся для прототипа на месяц; держать на них рабочий поток сделок мы не берёмся — под нагрузкой они перестают справляться первыми. Разбор ведёт Никита Бердников. Такую интеграцию мы собираем как приложение для Битрикс24 под задачу.

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

Коротко по сути

Входящий вебхук вызывает методы портала по секретному URL с правами создавшего его сотрудника и в границах выбранных прав. Исходящий шлёт события на ваш публичный URL, где обработчик сверяет токен, метку времени и идентификатор события.

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

Автор

Лаборатория внедрений

Внедряем и сопровождаем amoCRM и Битрикс24, делаем интеграции, разработку и аналитику. Пишем о том, что видим на аудитах и в проектах.

О компании

Направление на анализ

Начнём с пары вопросов

Ответьте на них, и мы свяжемся с вами в течение 2 рабочих часов.

Обсудить задачу на созвоне
MAX TG Обсудить задачу