9  /  46

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

Просмотров: 45707
Дата последнего изменения: 13.10.2020

Описание

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

Создание входящих вебхуков до версии модуля 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] => ххх
            )
    
    )

  Видео

Смотрите подробный мастер-класс о вебхуках:

Рекомендуем также посмотреть код, использованный в примерах.


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

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