← Назад к справке

REST

Входящие вебхуки

Рабочая справка по входящим вебхукам Bitrix24 REST: формат URL, вызов методов из PHP, обработка ответа и безопасность.

Входящий вебхук — самый простой способ вызвать REST-метод Bitrix24. Он работает от имени пользователя, который создал вебхук, и ограничен правами этого пользователя и выбранными правами вебхука.

Общее понимание

Вебхук подходит для внутренних интеграций, разовых импортов и простых серверных скриптов.

Что такое входящий вебхук

Входящий вебхук — это URL с ID пользователя и секретным кодом. Через этот URL можно вызывать REST-методы без отдельной OAuth-авторизации. 

https://portal.bitrix24.ru/rest/1/webhook_code/crm.item.list.json

Здесь 1 — ID пользователя, который создал вебхук, а webhook_code — секретный код вебхука.

Когда использовать

Подходит Лучше не использовать
Внутренние скрипты и интеграции. Публичные массовые приложения.
Импорт и выгрузка данных. Интерфейсные приложения внутри Bitrix24.
Простые автоматизации с CRM. Виджеты, чат-боты и сценарии, где нужен контекст приложения.

Ограничения

Вебхук не является полноценным приложением. Некоторые методы работают только в контексте приложения, например часть методов виджетов, телефонии, чат-ботов и коннекторов открытых линий.

Если нужно встраивание в интерфейс Bitrix24, авторизация разных пользователей или подписка приложения на события, лучше делать локальное приложение.

Вызов REST

REST-метод вызывается POST-запросом на URL вебхука.

Формат URL

https://portal.bitrix24.ru/rest/{user_id}/{webhook_code}/{method}.json

Пример для универсального получения сделок: 

https://portal.bitrix24.ru/rest/1/secret_code/crm.item.list.json

Вызов из PHP

<?php

const BITRIX24_WEBHOOK_URL = 'https://portal.bitrix24.ru/rest/1/secret_code/';

/**
 * Вызывает REST-метод Bitrix24 через входящий вебхук.
 */
function callBitrix24Webhook(string $method, array $parameters = []): array
{
    $url = BITRIX24_WEBHOOK_URL . $method . '.json';

    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($parameters),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
    ]);

    $response_body = curl_exec($curl);
    $curl_error = curl_error($curl);
    $status_code = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);

    curl_close($curl);

    if ($response_body === false) {
        return [
            'is_success' => false,
            'status_code' => $status_code,
            'error_messages' => [$curl_error],
            'data' => null,
        ];
    }

    $response_data = json_decode($response_body, true);

    return [
        'is_success' => $status_code >= 200 && $status_code < 300 && empty($response_data['error']),
        'status_code' => $status_code,
        'error_messages' => !empty($response_data['error_description'])
            ? [$response_data['error_description']]
            : [],
        'data' => $response_data,
    ];
}

$result = callBitrix24Webhook('crm.item.list', [
    'entityTypeId' => 2,
    'select' => [
        'id',
        'title',
        'stageId',
    ],
    'filter' => [
        '>id' => 0,
    ],
]);

print_r($result);

Обработка ответа

Успешный ответ обычно содержит result. При ошибке могут прийти error и error_description. 

/**
 * Возвращает result из ответа REST.
 */
function fetchRestResult(array $response)
{
    return $response['data']['result'] ?? null;
}

/**
 * Возвращает ошибки REST.
 */
function fetchRestErrors(array $response): array
{
    if (!empty($response['error_messages'])) {
        return $response['error_messages'];
    }

    if (!empty($response['data']['error_description'])) {
        return [
            $response['data']['error_description'],
        ];
    }

    return [];
}

$items = fetchRestResult($result);
$error_messages = fetchRestErrors($result);

Безопасность

URL входящего вебхука — это секрет. Его нельзя хранить в публичном JS и репозитории.

Почему URL нельзя светить

Если URL вебхука утечёт, внешний человек сможет вызывать REST-методы в рамках прав этого вебхука. Поэтому URL хранят в конфиге на сервере, в переменных окружения или в закрытых настройках.

Проверочный скрипт

<?php

const BITRIX24_WEBHOOK_URL = 'https://portal.bitrix24.ru/rest/1/secret_code/';

/**
 * Проверяет, от какого пользователя работает вебхук.
 */
function checkWebhookUser(): array
{
    return callBitrix24Webhook('user.current');
}

$user_result = checkWebhookUser();

print_r($user_result);

Первый тест после создания вебхука — вызвать user.current и убедиться, что скрипт работает от ожидаемого пользователя.

Источники