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

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

Что выбратьЧто выбрать

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

Входящий вебхук выбирают для внутренних интеграций и быстрых проверок, когда:

• нужно быстро проверить вызов метода в браузере, генераторе запросов или через curl
• интеграция работает только с одним Битрикс24
• запросы должны выполняться от имени конкретного сотрудника
• не нужен интерфейс приложения, обработчик событий или установка решения на другие Битрикс24

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

Права входящего вебхука определяются сотрудником, который его создал, и списком выбранных scope:

• создать входящий вебхук может администратор или сотрудник, которому администратор разрешил создание вебхуков
• на Битрикс24 должен быть доступ к REST API
• запросы выполняются в рамках scope, который выбран в настройках вебхука
• запросы выполняются с правами сотрудника, который создал вебхук
• секретный код вебхука доступен только сотруднику, который его создал. Если администратор отредактирует чужой вебхук, секретный код обновится, а владельцем вебхука станет администратор
• часть методов через вебхук недоступна, потому что требует контекста приложения. Например, методы встраивания виджетов, такие как placement.bind, часть методов телефонии и некоторые сценарии чат-ботов
• механизм входящих вебхуков поддерживает дату окончания. Если срок действия истек, запрос перестанет проходить и вернет ошибку авторизации

Как создать входящий вебхукКак создать входящий вебхук

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

1. Откройте раздел Приложения > Разработчикам
2. Перейдите на вкладку Готовые сценарии > Другое > Входящий вебхук
3. В генераторе запросов выберите метод и при необходимости заполните параметры
4. Нажмите Выполнить, чтобы проверить тестовый вызов
5. Укажите права доступа и нажмите Создать

В генераторе запросов можно выбрать метод, посмотреть описание метода и параметров, заполнить параметры, выполнить запрос и скачать готовый пример кода на PHP.

Если пункта Входящий вебхук нет, значит право на создание вебхуков закрыто. Попросите администратора дать доступ к созданию вебхуков.

Как устроен URL вебхукаКак устроен URL вебхука

Пример URL:

https://example.bitrix24.ru/rest/1/xxxxxxxx/department.get.json?ID=42

URL состоит из нескольких частей:

• example.bitrix24.ru — адрес вашего Битрикс24
• /rest — путь к REST API
• /1 — идентификатор сотрудника, который создал вебхук
• /xxxxxxxx — секретный код вебхука
• /department.get — имя вызываемого метода
• .json — формат ответа. Этот суффикс можно не указывать, по умолчанию используется json
• ?ID=42 — параметры метода

Как настроить доступ к созданию вебхуков для сотрудниковКак настроить доступ к созданию вебхуков для сотрудников

Сотрудник без прав администратора не может сам выдать себе доступ. Администратор может разрешить создание вебхуков всем сотрудникам или отдельным пользователям.

1. Откройте Настройки > Настройки Битрикс24. Раздел доступен только сотрудникам с правами администратора.
2. В новом окне перейдите в Безопасность > Интеграции Битрикс24.
3. В поле Кому разрешить создавать входящие вебхуки нажмите Добавить и выберите всех сотрудников или отдельных пользователей

Как быстро проверить метод через GET-запросКак быстро проверить метод через GET-запрос

На страницах методов REST API вызовы через вебхук показаны как POST-запросы. GET-запрос можно выполнить в адресной строке браузера или генераторе запросов при создании входящего вебхука.

Такой формат подходит, когда нужно быстро проверить простой вызов и посмотреть, как параметры выглядят в URL.

Общий формат URL:

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

Пример метода без параметров:

https://example.bitrix24.ru/rest/1/xxxxxxxx/profile.json

Пример метода с одним параметром:

https://example.bitrix24.ru/rest/1/xxxxxxxx/department.get.json?ID=1

Пример метода с массивом параметров:

https://example.bitrix24.ru/rest/1/xxxxxxxx/user.get.json?FILTER[ACTIVE]=true&select[]=ID&select[]=NAME

Что проверить перед рабочим использованиемЧто проверить перед рабочим использованием

Перед рабочим запуском проверьте, что:

• нужный метод доступен по выбранному scope
• у сотрудника, который создал вебхук, есть права на нужный объект
• у вашего Битрикс24 есть доступ к REST API
• запросы идут по HTTPS

Исходящий вебхукИсходящий вебхук

Исходящий вебхук выбирают, когда:

• внешняя система должна автоматически узнавать об изменениях в Битрикс24
• нужно запустить синхронизацию после создания или изменения объекта
• достаточно получить событие и идентификатор объекта, а подробные данные можно запросить отдельным методом

Как работает исходящий вебхукКак работает исходящий вебхук

Исходящий вебхук не вызывает метод сам. Он передает событие на ваш обработчик, а обработчик уже решает, нужен ли дополнительный запрос к REST API:

• вы выбираете событие и URL обработчика
• при наступлении события Битрикс24 отправляет POST-запрос на этот URL
• обработчик получает название события, основные данные об объекте и служебные поля авторизации
• если нужны полные данные об объекте, обработчик обычно вызывает соответствующий метод через входящий вебхук или приложение

Как создать исходящий вебхукКак создать исходящий вебхук

1. Откройте раздел Приложения > Разработчикам
2. Перейдите на вкладку Готовые сценарии > Другое > Исходящий вебхук
3. Укажите URL вашего обработчика
4. Выберите событие, на которое должен реагировать вебхук
5. Нажмите Создать и проверьте вызов после тестового изменения данных

URL обработчика должен быть публичным и доступным из внешней сети. Не указывайте localhost, адреса из локальной сети и обработчики с самоподписанным SSL-сертификатом.

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

Что получает обработчикЧто получает обработчик

Данные приходят как параметры HTTP-запроса с типом application/x-www-form-urlencoded. В PHP их удобно читать через $_REQUEST.

Пример структуры для события ONCRMDEALUPDATE:

Array
(
    [event] => ONCRMDEALUPDATE
    [data] => Array
        (
            [FIELDS] => Array
                (
                    [ID] => 662
                )
        )
    [ts] => 1724140800
    [auth] => Array
        (
            [domain] => example.bitrix24.ru
            [member_id] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
            [application_token] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        )
)

Параметры запроса:

В типовом сценарии обработчик берет идентификатор сделки из data[FIELDS][ID], а затем вызывает метод crm.item.get с entityTypeId = 2, чтобы получить полные данные.

Как проверить подлинность запросаКак проверить подлинность запроса

Сравните значение auth[application_token] в запросе со значением токена, которое показано в настройках исходящего вебхука. Если значения не совпадают, такой запрос нельзя считать доверенным.

Ограничения исходящего вебхукаОграничения исходящего вебхука

Перед настройкой исходящего вебхука учитывайте, что:

• в коробочной версии Битрикс24 для исходящего вебхука нужна активная лицензия
• на деморежимах исходящий вебхук недоступен
• URL обработчика должен быть доступен из внешней сети и принимать POST-запросы
• для коробочной версии нужно открыть необходимые сетевые доступы

Когда вебхука недостаточноКогда вебхука недостаточно

Выбирайте локальное приложение или OAuth 2.0, если:

• интеграцию нужно устанавливать на разные Битрикс24
• нужен интерфейс внутри Битрикс24
• нужны методы, которые работают только в контексте приложения
• нужно централизованно управлять авторизацией без передачи URL вебхука

Продолжите изучениеПродолжите изучение

• Раздел Разработчикам в Битрикс24
• Локальные приложения
• Локальные интеграции: сценарии использования
• Как выполнить свой первый запрос к API
• Доступные скоупы Битрикс24
• Полный протокол авторизации OAuth 2.0