8  /  44

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

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

Описание

Если коротко описать механизм вебхуков, то он заключается в том, что через пользовательский интерфейс Битрикс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 вебхука заполнить в константе C_REST_WEB_HOOK_URL файла settings.php, сформировать параметры для создания лида в переменной $queryData и разместить код из примера ниже в файле index.php SDK CRest.

    Внимание! Данный пример работает на основе SDK CRest. Перед использованием примера необходимо открыть через браузер файл checkserver.php и проверить корректность настроек вашего сервера. Подробнее.

    Пример кода обращения к Битрикс24
    <?php
    require_once(__DIR__ . '/crest.php');

    $defaults = [
    'first_name' => '',
    'last_name' => '',
    'phone' => '',
    'email' => ''
    ];

    if (array_key_exists('saved', $_REQUEST))
    {
    $defaults = $_REQUEST;

    $queryData = [
    'fields' => [
    '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' => [['VALUE' => $_REQUEST['phone'], 'VALUE_TYPE' => 'WORK']],
    'EMAIL' => [['VALUE' => $_REQUEST['email'], 'VALUE_TYPE' => 'WORK']],
    ],
    'params' => ['REGISTER_SONET_EVENT' => 'Y'],
    ];

    $result = CRest::call(
    'crm.lead.add',
    $queryData
    );

    if (array_key_exists('error', $result))
    {
    echo 'Ошибка при сохранении лида: ' . $result['error_description'];
    }
    else
    {
    echo 'Данные сохранены';
    }
    }
    ?>
    <form 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] => ххх
            )
    
    )

  Видео

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

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


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

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