9  /  48

Вебхуки. Быстрый старт

Просмотров: 205341
Дата последнего изменения: 10.09.2024
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
1
2
3
4
5

Описание

Краткое описание механизма вебхуков: через пользовательский интерфейс Битрикс24 можно получить и зафиксировать ключ авторизации. Этот ключ в дальнейшем можно использовать для вызова методов REST, и при этом данный ключ не ограничивается по сроку действия (в отличие от токенов авторизации протокола OAuth 2.0).

Это делает вебхуки исключительно простым и удобным механизмом для работы с REST, но при этом надо понимать, что эта простота имеет и свои недостатки:

  1. Для формирования вебхука требуется участие пользователя (вы не сможете генерировать вебхуки автоматически);
  2. Поскольку срока действия у вебхука нет, то любая "утечка" URL вебхука чревата получением доступа к вашему Битрикс24 в рамках прав конкретного вебхука. Именно поэтому данный механизм годится для "внутренних" интеграций, но не подходит для тиражных вариантов использования;
  3. Ряд методов REST недоступен для работы через вебхуки, поскольку их логика требует "контекста" приложения, а никакого приложения в терминах Битрикс24 для вебхуков нет (в частности, методы встраивания приложений в интерфейс Битрикс24, события телефонии, часть событий чат-ботов и т.д.).

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

Внимание! До версии 22.300.0 модуля REST невозможно обратиться к модулям в названии которых присутствует точка. Например: zenden.shop, zenden.exchange и подобное.

  Создание Входящего вебхука

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

Создать входящий вебхук можно из раздела Разработчикам Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24.

Подробнее...
(Приложения > Разработчикам, вкладка "Готовые сценарии" > Другое > Входящий вебхук).

В открывшейся форме:

  • измените название вебхука;
  • в генераторе запросов выберите метод REST API (можно прочитать описание метода и скачать готовый пример кода с необходимыми параметрами для выполнения запросов);
  • проверьте работу вебхука, нажав на кнопку Выполнить;
  • укажите права доступа, разрешив выполнять запросы только определенным инструментам Битрикс24.

В генераторе запросов будет представлен образец URL, который нужно использовать при отправке данных из сторонней системы в Битрикс24

URL состоит из:

  • doc-test-b24.bitrix24.ru - адрес вашего Битрикс24
  • /rest - указание на то, что работа ведётся через rest с вебхуками
  • /1 - идентификатор пользователя, создавшего вебхук
  • /173glortu42lvpju - секретный код

    Внимание! Данный код является конфиденциальной информацией. Его необходимо держать в секрете.

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

  • /crm.contact.get - вызываемый метод REST API Битрикс24 - программный продукт в виде облачного сервиса, а также коробочной версии, созданный компанией "1С-Битрикс".

    Разработчики могут создавать собственные приложения или интеграции для Битрикс24, используя открытый REST API, который работает как с облачным, так и с коробочным Битрикс24, а также с "1С-Битрикс: Управление сайтом" начиная с версии 16.6.0.

    Подробнее...
    . В данном случае - метод, возвращающий контакт по идентификатору
  • .json - необязательный параметр ("транспорт"). При создании новых вебхуков можно не указывать (по умолчанию будет использоваться .json). В конструкторе готовых решений .json подставляется явно
  • ?ID=42 - параметры, необходимые для конкретного метода. В данном случае - идентификатор. Параметры указываются после вопросительного знака и разделяются символом &

Создание входящих вебхуков до версии модуля REST 20.5.0

  Создание исходящего вебхука

Внимание! Для работы исходящего вебхука в коробочной версии Битрикс24 обязательна активная лицензия, на демо-порталах исходящий вебхук работать не будет.

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

Создать исходящий вебхук можно из раздела Разработчикам Начиная с версии модуля REST 20.5.0, доступен новый раздел Разработчикам (Приложения > Разработчикам), в котором собраны удобные инструменты для облегчения работы по интеграции и доработке вашего Битрикс24.

Подробнее...
(Приложения > Разработчикам, вкладка "Готовые сценарии" > Другое > Исходящий вебхук).

В открывшейся форме:

  1. измените название вебхука;
  2. укажите URL вашего обработчика - страницу на стороннем ресурсе, куда будет обращаться вебхук;
  3. выберите событие, на которое будет инициализироваться вебхук.
  4. При создании исходящего вебхука будет выведен токен в виде строки из случайных знаков. Этот код позволит внутри обработчика проверить, действительно ли обработчик вызван вашим Битрикс24.

  5. На странице обработчика разместите код:

    Пример кода обработчика для события ONCRMDEALUPDATE

    <?
    print_r($_REQUEST);
    writeToLog($_REQUEST, 'incoming');
    /**
    	* Write data to log file.
    	*
    	* @param mixed $data
    	* @param string $title
    	*
    	* @return bool
    	*/
    function writeToLog($data, $title = '') {
    	$log = "\n------------------------\n";
    	$log .= date("Y.m.d G:i:s") . "\n";
    	$log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
    	$log .= print_r($data, 1);
    	$log .= "\n------------------------\n";
    	file_put_contents(getcwd() . '/hook.log', $log, FILE_APPEND);
    	return true;
    } 

    Для проверки откройте любую сделку на редактирование и сохраните изменения, в логе отобразится примерно такая история:

    2017.01.17 12:58:29
    incoming
    Array
    (
    	[event] => ONCRMDEALUPDATE
    	[data] => Array
    		(
    			[FIELDS] => Array
    				(
    					[ID] => 662
    				)
    
    		)
    
    	[ts] => ххх
    	[auth] => Array
    		(
    			[domain] => ххх.bitrix24.ru
    			[client_endpoint] => https://ххх.bitrix24.ru/rest/
    			[server_endpoint] => https://oauth.bitrix.info/rest/
    			[member_id] => ххх
    			[application_token] => ххх
    		)
    
    )

21
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии
Доступна новая документация по REST: понятнее описания, больше примеров, удобнее поиск
Перейти