Что такое вебхуки

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

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

Какие бывают вебхуки

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

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

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

Ключи доступа не имеют срока годности, потеря ключа означает потерю контроля над функционалом вебхука
Возможности этой технологии ограничены, эти ограничения вызваны особенностями REST и обойти их не получится
В облачной редакции портала есть лимит на частоту запросов, он не должен превышать 2 запроса в секунду

В коробочной версии Битрикс24 ограничений по частоте запросов нет, но все остальные — сохраняются.

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

Входящие вебхуки поступают изначально в ваш портал. Хотим получить список задач некоторого юзера — послали соответствующий запрос в портал, нам вернулся некоторый массив данных. Хотим получить информацию о сделке с айди равным 5211 — аналогично посылаем соответствующий запрос в портал, получаем информацию о сделке.

Пример URL, для вызова REST с подробный разбор URL-ссылки:

https://********bitrix24.ru/rest/313/seycsj9qf5hbgrua/profile/

******* наименование корпоративного портала
/rest/ подтверждение того, что этот адрес относиться к Битрикс24 вебхукам
/313/ определитель пользователя, который создал webhook
/seycsj9qf5hbgrua/ секретный код
/profile/ метод REST выполняемый вами, когда вы прибегаете к использованию webhooks. Разработчик должен самостоятельно заняться подбором данного метода. Он будет напрямую зависеть от конечной цели создания вебхука в Битрикс24

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

Исходящие вебхуки инициируются порталом и отправляются сами из него во внешний обработчик. Они срабатывают при наступлении некоторых событий в портале. Например, создал кто-то задачу — это событие. И вот во внешний обработчик из портала уже посылается некоторый массив данных, содержащий информацию об этом событии, этой задаче. Тут важно, чтобы этот некоторый обработчик смог корректно принять, обработать поступивший к нему запрос. Под внешним обработчиком понимаем в рамках статьи некоторый ресурс, имеющий url с https и на нем уже обработка поступившего POST-запроса.

Требования для работы с вебхуками и документация

Для работы с вебхуками нужна подписка на Маркет. Она оформляется в соответствующем разделе Маркет левого меню портала.

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

Дальше рекомендую установить бесплатное приложение Документация по REST API. В нем можно доку почитать и отправить соответствующий вебхук попробовать. Оно появится в разделе Установленных приложений.

Также не лишним будет использовать Документацию по REST.

Библиотеки для работы

JS

Если ваше приложение реализует пользовательский интерфейс внутри Битрикс24, выводится на специальной странице или использует инструменты встройки, нужно воспользоваться возможностями специальной JS-библиотеки. Она представляет собой, JS SDK для REST что позволяет обращаться к REST прямо из front-end вашего приложения не погружаясь в реализацию авторизации по OAuth 2.0, предлагает ряд дополнительных функций для взаимодействия пользовательского интерфейса вашего приложения с интерфейсом Битрикс24. Для внешних приложений и вебхуков библиотека использоваться не может.

Подключается библиотека следующим образом:

<script src="//api.bitrix24.com/api/v1/"></script>

PHP

Использование REST API позволяет достаточно просто решать многие задачи интеграции внешних источников или систем с Битрикс24.

Crest небольшой PHPSDK для использования REST API Битрикс24 в локальных приложениях, тиражных приложениях или через вебхуки. Библиотеку можно скачать с репозитория.