8  /  36

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

Просмотров: 3096 (Статистика ведётся с 06.02.2017)

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

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

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

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

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

  1. В выпадающем меню Добавить вебхук выберите Входящий вебхук.
  2. В открывшейся форме заполните поля:
    • Название и Описание - произвольные данные.
    • Права доступа - укажите, к каким модулям вебхук должен иметь доступ. Доступен множественный выбор.
  3. После сохранения появится код для авторизации вебхука:

    Внимание! Данный код является конфиденциальной информацией. Его необходимо держать в секрете.
  4. Вместе с кодом будет представлен образец URL, который нужно использовать при отправке данных из сторонней системы в Битрикс24:
    https://********.bitrix24.ru/rest/1/83te1pjdphsa9u15/profile/
    где:
    • ******** - имя вашего портала;
    • /rest/ - указание системе на то, что данный адрес относится в вебхукам;
    • /1/ - идентификатор пользователя, создавшего вебхук. Под правами этого пользователя будет работать этот вебхук.
    • /83te1pjdphsa9u15/ - секретный код;
    • /profile/ - метод REST, который вы хотите выполнить, обращаясь к вебхуку. Разработчик должен сам подобрать метод из REST API в зависимости от целей создания вебхука.
  5. Обратиться из сторонней системы по указанному адресу на Битрикс24.

    Рассмотрим пример такого обращения с задачей создать лид из формы. Надо сформировать URL в переменной $queryUrl, сформировать параметры для создания лида в переменной $queryData и после подготовительных шагов как раз и обратиться к Битрикс24 при помощи функции curl_exec. Полученный в виде JSON результат обработан:

    Пример кода обращения к Битрикс24
    <?
    /**
     * 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;
    }
    
    $defaults = array('first_name' => '', 'last_name' => '', 'phone' => '', 'email' => '');
    
    if (array_key_exists('saved', $_REQUEST)) {
     $defaults = $_REQUEST;
     writeToLog($_REQUEST, 'webform');
    
     $queryUrl = 'https://restapi.bitrix24.ru/rest/1/31uhq2q855fk1foj/crm.lead.add.json';
     $queryData = http_build_query(array(
     'fields' => array(
     "TITLE" => $_REQUEST['first_name'].' '.$_REQUEST['last_name'],
     "NAME" => $_REQUEST['first_name'],
     "LAST_NAME" => $_REQUEST['last_name'],
     "STATUS_ID" => "NEW",
     "OPENED" => "Y",
     "ASSIGNED_BY_ID" => 1,
     "PHONE" => array(array("VALUE" => $_REQUEST['phone'], "VALUE_TYPE" => "WORK" )),
     "EMAIL" => array(array("VALUE" => $_REQUEST['email'], "VALUE_TYPE" => "WORK" )),
     ),
     'params' => array("REGISTER_SONET_EVENT" => "Y")
     ));
    
     $curl = curl_init();
     curl_setopt_array($curl, array(
     CURLOPT_SSL_VERIFYPEER => 0,
     CURLOPT_POST => 1,
     CURLOPT_HEADER => 0,
     CURLOPT_RETURNTRANSFER => 1,
     CURLOPT_URL => $queryUrl,
     CURLOPT_POSTFIELDS => $queryData,
     ));
    
     $result = curl_exec($curl);
     curl_close($curl);
    
     $result = json_decode($result, 1);
     writeToLog($result, 'webform result');
    
     if (array_key_exists('error', $result)) echo "Ошибка при сохранении лида: ".$result['error_description']."
    "; } ?> <fo rm method="post" action=""> Имя: <input type="text" name="first_name" size="15" value="<?=$defaults['first_name']?>"><br/> Фамилия: <input type="text" name="last_name" size="15" value="<?=$defaults['last_name']?>"><br/> Телефон: <input type="phone" name="phone" value="<?=$defaults['phone']?>"<
    E-mail: <input type="email" name="email" value="<?=$defaults['email']?>"><br/> <input type="hidden" name="saved" value="yes"> <input type="submit" value="Отправить"> </form>

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

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

  1. В выпадающем меню Добавить вебхук выберите Исходящий вебхук.
  2. В открывшейся форме заполните поля:
    • Адрес обработчика - страница на стороннем ресурсе, куда будет обращаться вебхук.
    • Название и Описание - произвольные данные.
    • Тип события - нужно указать событие, на которое будет инициализироваться вебхук.
  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] => ххх
            )
    
    )

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

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


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

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