Вебхуки служат для взаимодействия портала Битрикс24 с внешними обработчиками данных. Бывают Входящие и Исходящие.
Входящие вебхуки поступают изначально В ваш портал. Хотим получить список задач некоторого юзера - послали соответствующий запрос В портал, нам вернулся некоторый массив данных. Хотим получить информацию о сделке с айди равным 5211 - аналогично посылаем соответствующий запрос В портал, получаем информацию о сделке.
Примеры создания входящего вебхука на python в отдельной статье>>
Исходящие вебхуки инициируются порталом и отправляются сами ИЗ него во внешний обработчик. Они срабатывают при наступлении некоторых событий в портале. Например, создал кто-то задачу - это событие. И вот во внешний обработчик ИЗ портала уже посылается некоторый массив данных, содержащий информацию об этом событии, этой задаче. Тут важно, чтобы этот некоторый обработчик смог корректно принять, обработать поступивший к нему запрос. Под внешним обработчиком понимаем в рамках статьи некоторый ресурс, имеющий url с https (адрес ресурса) и на нем уже обработка поступившего POST-запроса.
Обрабатываем Исходящие вебхуки Битрикс24 из роботов на Питоне>>
Детально, как на Питоне работать с обоими типами этих вебхуков рассмотрим в последующих статьях, а пока представление о них.
- Требования для работы с вебхуками и документация.
- Где и как создавать вебхуки Битрикс24.
- Пример запуска.
1. Требования для работы с вебхуками и документация
Для работы с вебхуками нужна подписка на Маркет. Она оформляется в соответствующем разделе Маркет левого меню портала.
Ваши вебхуки не должны быть скомпрометированы, не попасть никуда в публичное поле, т.к. с этим злоумышленники легко смогут получать данные из вашего портала. При определенных условиях из соображений безопасности вендор блокирует такие хуки и они перестают работать, например, при их обнаружении на Гитхабе,
Дальше рекомендую установить бесплатное приложение Документация по REST API. В нем можно доку почитать и отправить соответствующий вебхук попробовать. Оно появится в разделе Установленных приложений
Также не лишним будет использовать Документацию по REST.
2. Где и как создавать вебхуки Битрикс24
Левое меню -> Раздел Разработчикам (можно по адресу https://<url_your_bitrix24>/devops/) -> Другое -> Выбираем Входящий или Исходящий хук.
Начнем с создания Входящего вебхука. Открывается страничка с некоторыми данными/полями:
Вебхук для вызова rest api. Это собственно, то, что нам и будет нужно для создания запроса. Посылать будем на этот адрес. Ссылка имеет формат:
https://<url_your_bitrix24>/rest/<id_user>/<secret_token>/
<url_your_bitrix24> - адрес вашего портала;
<id_user> - айди создавшего пользователя, важно, если у пользователя нет доступа к некоторым данным, то и его вебхук не должен их тоже получать;
<secret_token> - секретный ключ для доступа, если есть сомнения, что вебхук стал кому-то еще доступен, просто нажимаете кнопку Перегенерировать и получите новый токен.
Настройка прав. Это второй необходимый пункт для работы хука. Тут выбираем те права, которые ему будут нужны. Выбрать просто все права явно не безопасное решение и так делать не надо. Если хотим, чтобы он работал с задачами, указываем Задачи(tasks), для CRM - CRM(crm).
Для Исходящего хука интерфейс проще. Тут надо указать:
- URL вашего обработчика* - Куда Битрикс24 будет посылать запрос при наступлении события;
- События - при наступлении каких событий портал должен "написать" в обработчик на url выше.
Если хотим, чтобы портал сообщал нам о создании сделки, надо указать событие Создание сделки (ONCRMDEALADD), а для добавления нового пользователя - Добавление пользователя в Битрикс24 (ONUSERADD).
Найти и редактировать созданные вебхуки можно в разделе Левое меню -> Раздел Разработчикам -> Интеграции. Или по адресу https://<url_your_bitrix24>/devops/list/.
Относительно полный перечень событий, на которые можно повесить Исходящие вебхуки будет в конце статьи.
3. Пример запуска
Тут покажу на примере Входящего вебхука. Как получить информацию о сделке по ее айди.
Для этого воспользуемся разделом Генератор запросов на странице создания Входящего хука, который проигнорировали в п.2. Информацию о сделке такую в т.ч. нам может вернуть метод crm.deal.get. Из параметров по доке он имеет только один параметр "id", соответствующий айди нашей сделки. Поэтому это и указываем на странице хука в Генераторе запросов.
Нажимаем Выполнить и получаем информацию о сделке с айди равным 22292:
Примеры событий для Исходящих вебхуков:
Добавление пользователя в Битрикс24 (ONUSERADD)
Добавление события календаря (ONCALENDARENTRYADD)
Изменение события календаря (ONCALENDARENTRYUPDATE)
Удаление события календаря (ONCALENDARENTRYDELETE)
Добавление секции календаря (ONCALENDARSECTIONADD)
Изменение секции/ресурса календаря (ONCALENDARSECTIONUPDATE)
Удаление секции/ресурса календаря (ONCALENDARSECTIONDELETE)
Новое сообщение боту (ONIMBOTMESSAGEADD)
Обновление сообщения чат-ботом (ONIMBOTMESSAGEUPDATE)
Удаление сообщения чат-ботом (ONIMBOTMESSAGEDELETE)
Включение бота в чат (ONIMBOTJOINCHAT)
Удаление бота (ONIMBOTDELETE)
Команда боту (ONIMCOMMANDADD)
Инициация звонка (ONVOXIMPLANTCALLINIT)
Начало разговора (ONVOXIMPLANTCALLSTART)
Завершение разговора (ONVOXIMPLANTCALLEND)
Инициация звонка через приложение (ONEXTERNALCALLSTART)
Инициация звонка по запросу обратного звонка из CRM-виджета (ONEXTERNALCALLBACKSTART)
Сохранение заказа интернет-магазина (ONSALEORDERSAVED)
Удаление заказа интернет-магазина (ONSALEBEFOREORDERDELETE)
Сохранение значения свойства интернет-магазина (ONPROPERTYVALUEENTITYSAVED)
Сохранение оплаты интернет-магазина (ONPAYMENTENTITYSAVED)
Сохранение отгрузки интернет-магазина (ONSHIPMENTENTITYSAVED)
Сохранение заказа интернет-магазина (ONORDERENTITYSAVED)
Удаление свойства из базы интернет-магазина (ONPROPERTYVALUEDELETED)
Удаление оплаты из базы интернет-магазина (ONPAYMENTDELETED)
Удаление отправки из базы интернет-магазина (ONSHIPMENTDELETED)
Удаление сущности из базы интернет-магазина (ONORDERDELETED)
Создание счета (ONCRMINVOICEADD)
Обновление счета (ONCRMINVOICEUPDATE)
Удаление счета (ONCRMINVOICEDELETE)
Обновление статуса счета (ONCRMINVOICESETSTATUS)
Создание лида (ONCRMLEADADD)
Обновление лида (ONCRMLEADUPDATE)
Удаление лида (ONCRMLEADDELETE)
Добавление пользовательского поля в событиях (ONCRMLEADUSERFIELDADD)
Изменение пользовательского поля в событиях (ONCRMLEADUSERFIELDUPDATE)
Удаление пользовательского поля в событиях (ONCRMLEADUSERFIELDDELETE)
Изменение набора пользовательского поля в сделках (ONCRMLEADUSERFIELDSETENUMVALUES)
Создание сделки (ONCRMDEALADD)
Обновление сделки (ONCRMDEALUPDATE)
Удаление сделки (ONCRMDEALDELETE)
Добавление пользовательского поля в сделках (ONCRMDEALUSERFIELDADD)
Изменение пользовательского поля в сделках (ONCRMDEALUSERFIELDUPDATE)
Удалении пользовательского поля в сделках (ONCRMDEALUSERFIELDDELETE)
Изменение набора значений поля в сделках (ONCRMDEALUSERFIELDSETENUMVALUES)
Создание компании (ONCRMCOMPANYADD)
Обновление компании (ONCRMCOMPANYUPDATE)
Удаление компании (ONCRMCOMPANYDELETE)
Добавлении пользовательского поля событий компании (ONCRMCOMPANYUSERFIELDADD)
Изменение пользовательского поля событий компании (ONCRMCOMPANYUSERFIELDUPDATE)
Удаление пользовательского поля событий компании (ONCRMCOMPANYUSERFIELDDELETE)
Изменение набора для поля компании (ONCRMCOMPANYUSERFIELDSETENUMVALUES)
Создание контакта (ONCRMCONTACTADD)
Обновление контакта (ONCRMCONTACTUPDATE)
Удаление контакта (ONCRMCONTACTDELETE)
Добавление пользовательского поля контактов (ONCRMCONTACTUSERFIELDADD)
Изменение пользовательского поля контактов (ONCRMCONTACTUSERFIELDUPDATE)
Удаление пользовательского поля контактов (ONCRMCONTACTUSERFIELDDELETE)
Изменение значений пользовательского поля контактов (ONCRMCONTACTUSERFIELDSETENUMVALUES)
Создание коммерческого предложения (ONCRMQUOTEADD)
Изменение коммерческого предложения (ONCRMQUOTEUPDATE)
Удаление коммерческого предложения (ONCRMQUOTEDELETE)
Добавление пользовательского поля коммерческого предложения (ONCRMQUOTEUSERFIELDADD)
Изменение пользовательского поля коммерческого предложения (ONCRMQUOTEUSERFIELDUPDATE)
Удаление набора пользовательского поля коммерческого предложения (ONCRMQUOTEUSERFIELDDELETE)
Изменение набора пользовательского поля коммерческого предложения (ONCRMQUOTEUSERFIELDSETENUMVALUES)
Добавление пользовательского поля счета (ONCRMINVOICEUSERFIELDADD)
Изменение пользовательского поля счета (ONCRMINVOICEUSERFIELDUPDATE)
Удаление пользовательского поля счета (ONCRMINVOICEUSERFIELDDELETE)
Изменение поля списочного типа (ONCRMINVOICEUSERFIELDSETENUMVALUES)
Создание валюты (ONCRMCURRENCYADD)
Обновление валюты (ONCRMCURRENCYUPDATE)
Удаление валюты (ONCRMCURRENCYDELETE)
Создание товара (ONCRMPRODUCTADD)
Обновление товара (ONCRMPRODUCTUPDATE)
Удаление товара (ONCRMPRODUCTDELETE)
Добавление свойства товара (ONCRMPRODUCTPROPERTYADD)
Изменение свойства товара (ONCRMPRODUCTPROPERTYUPDATE)
Удаление свойства товара (ONCRMPRODUCTPROPERTYDELETE)
Добавление раздела (ONCRMPRODUCTSECTIONADD)
Изменение раздела (ONCRMPRODUCTSECTIONUPDATE)
Удаление раздела (ONCRMPRODUCTSECTIONDELETE)
Создание дела (ONCRMACTIVITYADD)
Обновление дела (ONCRMACTIVITYUPDATE)
Удаление дела (ONCRMACTIVITYDELETE)
Добавление реквизита (ONCRMREQUISITEADD)
Обновление реквизита (ONCRMREQUISITEUPDATE)
Удаление реквизита (ONCRMREQUISITEDELETE)
Добавление пользовательского поля (ONCRMREQUISITEUSERFIELDADD)
Изменение пользовательского поля (ONCRMREQUISITEUSERFIELDUPDATE)
Удаление пользовательского поля (ONCRMREQUISITEUSERFIELDDELETE)
Изменение набора значений для пользовательского поля списочного типа (ONCRMREQUISITEUSERFIELDSETENUMVALUES)
Добавление банковского реквизита (ONCRMBANKDETAILADD)
Обновление банковского реквизита (ONCRMBANKDETAILUPDATE)
Удаление банковского реквизита (ONCRMBANKDETAILDELETE)
Регистрация адреса (ONCRMADDRESSREGISTER)
Удаление адреса (ONCRMADDRESSUNREGISTER)
Добавление единицы измерения (ONCRMMEASUREADD)
Изменение единицы измерения (ONCRMMEASUREUPDATE)
Удаления единицы измерения (ONCRMMEASUREDELETE)
Создание новой регулярной сделки (ONCRMDEALRECURRINGADD)
Обновление регулярной сделки (ONCRMDEALRECURRINGUPDATE)
Удаление регулярной сделки (ONCRMDEALRECURRINGDELETE)
Создание новой сделки из регулярной сделки (ONCRMDEALRECURRINGEXPOSE)
Создание нового регулярного счета (ONCRMINVOICERECURRINGADD)
Обновление регулярного счета (ONCRMINVOICERECURRINGUPDATE)
Удаление регулярного счета (ONCRMINVOICERECURRINGDELETE)
Выставление нового счета из регулярного счета (ONCRMINVOICERECURRINGEXPOSE)
Добавление нового комментария в таймлайне (ONCRMTIMELINECOMMENTADD)
Обновление комментария в таймлайне (ONCRMTIMELINECOMMENTUPDATE)
Удаление нового комментария в таймлайне (ONCRMTIMELINECOMMENTDELETE)
Добавление элемента смарт-процесса (ONCRMDYNAMICITEMADD)
Изменение элемента смарт-процесса (ONCRMDYNAMICITEMUPDATE)
Удаление элемента смарт-процесса (ONCRMDYNAMICITEMDELETE)
Создание нового смарт-процесса (ONCRMTYPEADD)
Изменение настроек смарт-процесса (ONCRMTYPEUPDATE)
Удаление смарт-процесса (ONCRMTYPEDELETE)
Создание нового документа (ONCRMDOCUMENTGENERATORDOCUMENTADD)
Изменение документа (ONCRMDOCUMENTGENERATORDOCUMENTUPDATE)
Удаление документа (ONCRMDOCUMENTGENERATORDOCUMENTDELETE)
ONCRMTYPEUSERFIELDADD
ONCRMTYPEUSERFIELDUPDATE
ONCRMTYPEUSERFIELDDELETE
ONCRMTYPEUSERFIELDSETENUMVALUES
Создание задачи (ONTASKADD)
Обновление задачи (ONTASKUPDATE)
Удаление задачи (ONTASKDELETE)
Добавление комментария к задаче (ONTASKCOMMENTADD)
Обновление комментария к задаче (ONTASKCOMMENTUPDATE)
Удаление комментария к задаче (ONTASKCOMMENTDELETE)
Добавление пользователя в Битрикс24 (ONUSERADD)
Удаление открытой линии (ONIMCONNECTORLINEDELETE)
Новое сообщение из ОЛ (ONIMCONNECTORMESSAGEADD)
Изменение сообщения из ОЛ (ONIMCONNECTORMESSAGEUPDATE)
Удаление сообщения из ОЛ (ONIMCONNECTORMESSAGEDELETE)
Отключение канала линии (ONIMCONNECTORSTATUSDELETE)
Добавление события живой ленты (ONLIVEFEEDPOSTADD)
Обновление события живой ленты (ONLIVEFEEDPOSTUPDATE)
Удаление события живой ленты (ONLIVEFEEDPOSTDELETE)
Добавление новой рабочей группы (ONSONETGROUPADD)
Изменение рабочей группы (ONSONETGROUPUPDATE)
Добавление рабочей группы (ONSONETGROUPDELETE)
Создание темы рабочих групп (ONSONETGROUPSUBJECTADD)
Изменение темы рабочих групп (ONSONETGROUPSUBJECTUPDATE)
Удаление темы рабочих групп (ONSONETGROUPSUBJECTDELETE)
