Вебхук в Битрикс24 — это способ связать портал с внешним сервисом без написания приложения: входящий вебхук даёт внешней системе URL-ключ для вызова REST API портала, исходящий — заставляет Битрикс24 самому стучаться на ваш URL при событии. Это самый быстрый способ интеграции, но у него есть границы, о которых справка молчит. Разберём оба типа, создание, ограничения и третий сценарий, который чаще всего и нужен: вебхук из бизнес-процесса.

Чем входящий вебхук отличается от исходящего?

Входящий — это URL вида https://портал.bitrix24.ru/rest/1/ключ/, по которому внешний сервис вызывает методы REST API: создать лид, обновить сделку, получить список задач. Права задаются при создании (только CRM, только задачи и т.д.), действия выполняются от имени сотрудника-владельца ключа. Исходящий — наоборот: вы указываете URL своего обработчика и событие (создан лид, обновлена сделка), и Битрикс24 отправляет туда POST при каждом срабатывании. Связка обоих типов даёт двустороннюю интеграцию: исходящий сообщает «появился контакт», внешний сервис обогащает данные и входящим вебхуком пишет их обратно.

Где создать вебхук и что проверить?

Раздел «Разработчикам» (в старых меню — «Приложения») → «Другое» → «Входящий вебхук» / «Исходящий вебхук». Для входящего: выберите права доступа по минимуму — ключ с правами «CRM + всё остальное» при утечке отдаёт злоумышленнику всю базу; скопируйте URL с ключом и храните его как пароль. Для исходящего: укажите URL обработчика и токен приложения для проверки подлинности — обработчик обязан сверять токен, иначе любой, узнавший адрес, сможет слать поддельные события. Доступность вебхуков зависит от тарифа: на части тарифов нужна подписка Битрикс24 Маркет.

Какие ограничения у вебхуков?

Три, о которые разбиваются интеграции. Лимит запросов: REST API принимает примерно два запроса в секунду на портал, при превышении — ошибка QUERY_LIMIT_EXCEEDED; массовые операции упаковывают в batch-вызовы. Исходящий вебхук не повторяет доставку: если ваш обработчик был недоступен три секунды, событие потеряно — Битрикс24 не ретраит. И исходящий вебхук несёт минимум данных (ID и тип события) — за полями всё равно идти входящим вебхуком в REST API. Поэтому «надёжная шина на исходящих вебхуках» — это миф: для критичных событий нужна доставка с подтверждением и повторами.

Как отправить вебхук из бизнес-процесса?

Частый сценарий, которого нет в штатных действиях: при переходе сделки на стадию дёрнуть внешний сервис — учётную систему, склад, мессенджер-бота. Это закрывают два робота Роботеки. «HTTP-запрос» отправляет GET или POST с заголовками и телом, возвращает ответ и статус-код в переменные процесса — для синхронных сценариев «спросил и получил ответ» (ответ разбирается роботом «Извлечь значение из JSON по пути»). «Отказоустойчивый вебхук» — для сценария «доставить обязательно»: он повторяет отправку при недоступности приёмника, и событие не теряется, пока внешний сервис перезагружается. Правило выбора: нужен ответ здесь и сейчас — HTTP-запрос; нужна гарантия доставки уведомления — отказоустойчивый вебхук.

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

Любой сотрудник, которому открыт раздел «Разработчикам», а не только администратор. В модуле REST администратору оставлены лишь некоторые готовые сценарии интеграций, например с виджетом в карточке. Простой входящий и исходящий вебхук сотрудник создаёт сам, и работает такой вебхук с правами этого сотрудника. Отдельного переключателя «вебхуки только для администраторов» нет. Поэтому администратору стоит время от времени просматривать список вебхуков (как его открыть — в следующем разделе). Запрет на создание не защищает от главного: вебхук, созданный сотрудником, видит в CRM ровно то же, что видит сам сотрудник.

Где посмотреть уже созданные вебхуки и как удалить ненужный?

«Разработчикам» → «Интеграции». Сотрудник видит в списке только свои вебхуки, администратор видит все и может отфильтровать их по автору. Ключ (секретная часть URL) показан только автору: администратор, открыв чужой вебхук, видит звёздочки вместо кода. Если интеграция работает, но никто не помнит, кто её делал, ищите её в этом списке по автору и дате, а не по URL. Удаляется вебхук через меню строки списка. После удаления внешняя система сразу начнёт получать ошибку авторизации, поэтому сначала выясните, кто этим ключом пользуется. Вебхуки уволенных сотрудников проверьте отдельно: что с ними происходит при увольнении, разобрано в статье про увольнение сотрудника.

Можно ли сделать вебхук только на чтение?

Галочки «только чтение» у входящего вебхука нет. Права при создании выбираются по модулям (CRM, задачи, пользователи и так далее), и внутри модуля вебхук может и читать, и писать. Ограничить его можно только правами того, от чьего имени он работает: вебхук выполняет запросы от имени автора и упирается в его роль. Отсюда рабочий способ. Заведите отдельного сотрудника под интеграции, дайте ему в CRM роль с правом только на чтение нужных сущностей и создайте вебхук от его имени. Такой ключ при утечке не позволит ничего изменить или удалить. Учтите, что этот сотрудник занимает место в лимите пользователей тарифа. Заодно интеграция перестанет зависеть от конкретного менеджера: увольнение человека не сломает обмен данными.

Что дать подрядчику, который будет присылать лиды?

Обычно просят «URL или вебхук», и в обоих случаях имеют в виду одно и то же: адрес входящего вебхука, на который их система будет отправлять вызов crm.lead.add. Выдавайте ключ с одним модулем CRM, созданный от имени сотрудника-интеграции из предыдущего раздела, а не от вашей учётной записи администратора. Этот адрес работает как пароль: кто его знает, тот пишет в вашу CRM. Если с подрядчиком расстались, удалите вебхук в списке интеграций, и доступ закроется сразу. Если подрядчику нужно только отправлять заявки с сайта, проще дать ему CRM-форму: ключ к REST API в этом случае вообще не понадобится.

Исходящий вебхук в роботах: что писать в поле «Обработчик»?

В списке роботов Битрикс24 есть штатный робот «Исходящий вебхук». У него одно поле, «Обработчик», и в нём указывается адрес вашего сервиса: http или https, с доменным именем. Робот отправляет туда запрос с идентификатором документа (document_id, например сделка DEAL_10) и сразу идёт дальше. Ответа он не ждёт и ничего не возвращает в процесс. Поля сделки он сам не передаёт. Нужные значения добавляют в адрес как параметры: https://example.com/hook?deal={=Document:ID}&sum={=Document:OPPORTUNITY}. Ещё одна особенность: если на тарифе недоступен REST, робот молча не делает ничего, и ошибки в журнале не будет. Когда нужен заголовок авторизации, тело в JSON или ответ сервиса в переменной процесса, используйте «HTTP-запрос». Когда событие нельзя потерять, используйте «Отказоустойчивый вебхук»: он повторяет отправку по расписанию, до десяти попыток.

Вебхук не работает: чек-лист

Входящий возвращает ошибку: проверьте права ключа (метод требует скоупа, которого нет), активность сотрудника-владельца (уволенный сотрудник = мёртвый ключ) и лимит запросов. Исходящий не приходит: проверьте, что обработчик отвечает кодом 200 быстро (долгий ответ Битрикс24 считает ошибкой), что URL доступен снаружи (не localhost, не закрыт фаерволом) и что событие действительно то — «обновление сделки» не срабатывает на смену стадии канбана задач. И помните про отсутствие ретраев: если приёмник лежал, событие надо восстанавливать руками — или изначально слать через отказоустойчивый вебхук из процесса.

Итог

Вебхуки — самый дешёвый способ интеграции с Битрикс24: входящий для управления порталом снаружи, исходящий для сигналов наружу, а из бизнес-процессов — роботы с HTTP-запросом и гарантией доставки из каталога Роботеки. Нет нужного сценария — опишите задачу, сделаем робота бесплатно.