Описание

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

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

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

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

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

Входящий вебхук используется для работы с данными вашего Битрикс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 - параметры, необходимые для конкретного метода. В данном случае - идентификатор. Параметры указываются после вопросительного знака и разделяются символом &

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

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

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

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

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

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

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



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

   Пример кода обработчика для события 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] => ххх
   		)
   
   )