Вебхук в Битрикс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-запрос; нужна гарантия доставки уведомления — отказоустойчивый вебхук.

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

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

Итог

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