что такое вебхуки битрикс 24
Области применения вебхуков на портале Битрикс24
Под вебхуком понимается реакций стороннего по отношению Битрикс24 приложения – как правило некоторого PHP – файла – на событие его запуска. Это событие может быть вызвано из Битрикс24 через инициализацию данного файла (исходящий вебхук) или открытия данного файла на стороне стороннего сервера с вызовом методов REST API (входящий вебхук). Допускается и очень часто применяется комбинация исходящего и входящего вебхука.
Вебхуки настраиваются в разделе приложений Битрикс24, также на них можно сослаться из роботов \ триггеров сущностей CRM \ задач, выполнить запуск исходящего вебхука из бизнес-процесса. При этом сам вебхук представляет собой всего лишь гиперссылку: входящий содержит адрес корпоративного портала, ключ авторизации, и вызываемый метод REST API. Исходящий вебхук – это всего лишь ссылка на сторонний сайт, работающий в https – режиме, куда передается некоторый набор данных в виде POST-запроса.
Вебхуки представляют из себя предельно простой инструмент интеграции – для вызова методов REST API не надо проходит ресурсоемкую процедуру регистрации нового внешнего приложения, задействовать механизмы авторизации по протоколу OATH 2.0. Средством авторизации выступает уникальный ключ, хранящийся в ссылке входящего и запросе исходящего вебхука, в целях безопасности эти ключи рекомендуется периодически обновлять.
Как можно догадаться, вебхуки дают нам мощную свободу действий, ограниченную лишь библиотекой методов REST API. Приведем возможные кейсы применения вебхуков.
| Кейс | Вариант реализации | Комментарий |
| При изменении ответственного в сделке заменить ответственного в связанных с ним задачах | Связать событие обновления сделки с исходящим вебхуком, вызывающим входящие вебхуки: по запросу данных полей сделке, связанных со сделкой задачах, обновлению данных задач, если там другой ответственный | Данный вебхук готовы предоставить читателям данной статьи по запросу |
| Сменить стадию в сделке с «Товар отгружается» на «Товар отгружен клиенту» при поступлении информации из сторонней системы | На стадию сделки «Товар отгружен клиенту» вешается триггер со ссылкой на входящий вебхук, который запускается из логистической системы с параметрами указанной сделки | |
| Автоматически поставить задачу с заполнением чек – листа при переходе лида на новую стадию | Робот перехода сделки на новую стадию связывается с соответствующим входящим вебхуком | |
| При закрытии задачи приема сотрудника на работу в систему выпуска пропусков передается информация о новом сотруднике, указанном в постановщике по задаче | С событием обновления задачи связывается вебхук, проверяющий была ли задача закрыта, соответствует ли она задаче приема сотрудника на работу и передающий информацию по этому сотруднику в систему заказа пропусков | |
| Компания, организующая корпоративное мероприятие, ставит из своей системы событие в календари участников данного мероприятия | Из информационной системы компании, организующей корпоративное мероприятие, вызывается входящий вебхук, который добавляет данные в календари его участников на Битрикс24 | |
| Необходимо наполнить базу CRM при запуске корпоративного портала, одновременно создав контакты, компании и связанные с ними лиды и сделки | Запускается PHP-файл, забирающий сведения из источника и добавляющий сведения на корпоративный портал с помощью серии входящих вебхуков | Методы REST API имеет ограничение на число добавляемых записей в 50 штук. Для выполнения задачи необходимо вызывать серию методов в пакетном режиме |
Как видим большая свобода действий в применении вебхуков обусловлена следующими причинами: возможность делать стыковки со сторонними системами, поддерживающие функционал веб-сервисов, использованием при вызове вебхуков богатства функций языка PHP (массивов, циклов, условных операторов, собственных объектов, классов и их методов).
Скрипты входящих вебхуков предельно легко отлаживать (запускать скрипт в адресной строке и выводить результат выполнения с помощью команды print_r), их можно ставить на обработку в пакетномм режме через cron.
С другой стороны нельзя забывать про ограничения вебхуков: невозможность создавать через них массово тиражируемые решения с выкладкой на маркетплейс Битрикс24, необходимость в целях безопасности периодической замены ключей авторизации.
Документация
Настройка веб хуков CRM
Перейдите на ваш сайт Битрикс24.
Перед началом настройки вебхуков создайте нового пользователя с полным набором прав, через которого будет осуществляться интеграция. Создание такого пользователя минимизирует конфликт соединения в процессе интеграции.
В дальнейшем по данному пользователю можно будет отслеживать сделки и счета перенесенные с сайта Битрикс.
В левом меню перейдите к разделу «Приложения», после чего перейдите к разделу «Вебхуки».
В открывшемся окне требуется создать входящий и ряд исходящих вебхуков.
Входящий вебхук
В правой верхней части экрана нажмите «Добавить вебхук» и в открывшемся списке выберете «Входящий вебхук».
В открывшемся окне укажите название вебхука, при необходимости введите описание и установите права доступа. Для работы модуля достаточно права «CRM».
Если работа с торговыми предложениями в Битрикс24 ведётся при помощи модуля CRM инструменты (sotbit.crmtools), то обязательно добавьте соответствующие права.
После заполнения требуемых полей нажмите кнопку «Сохранить».
В открывшемся окне появляются данные вебхука, которые потребуется указать в настройках модуля CRM на сайте Битрикс.
Исходящие вебхуки
В правой верхней части экрана нажмите «Добавить вебхук» и в открывшемся списке выберете «Исходящий вебхук».
В открывшемся окне заполните адрес обработчика, название и тип события.
Адрес обработчика должен быть вида: https:// Ваш сайт /api/crm/
После заполнения требуемых полей нажмите кнопку «Сохранить».
После сохранения вебхука появляется код авторизации, который потребуется перенести в настройки модуля CRM на сайте Битрикс.
Список требуемых вебхуков:
Рекомендации по заполнению полей
В поле «Название» укажите тип события, чтобы в последствии иметь возможность быстро найти и внести корректировки в требуемый вебхук.
Готовые сценарии вебхуков для разработчиков
Мы значительно упростили работу разработчика приложений для Битрикс24.
В новом разделе Разработчикам мы предлагаем готовые сценарии для интеграции и доработки вашего Битрикс24, а также список всех созданных вебхуков и статистику их использования.
Готовые сценарии
В этой вкладке содержатся уже готовые сценарии с примерами кода и предустановленными параметрами на базе вебхуков и локальных приложений. Мы постарались добавить наиболее частые сценарии работы с вебхуками, но вы всегда можете создать свои интеграции.
В настройках вебхуков мы предоставляем простой генератор REST-запросов, который помогает в режиме онлайн подобрать нужные значения параметров для дальнейшего использования во внешних системах.
В генераторе запросов можно выбрать метод REST API, прочитать описание метода, скачать пример, добавить свои параметры. Здесь же можно выполнить сам запрос и получить результат, проверив работу вебхука.
Добавление прав доступа позволит ограничить выполнение запросов для определенных инструментов Битрикс24.
Готовые сценарии разбиты по категориям:
Интегрировать с внешними системами
Интеграции
Администратор Битрикс24 может видеть все интеграции в одном разделе – кто создал, какие события вызывают вебхуки, какие доступы предоставлены вебхуку или приложению. Учитываются все приложения, использующие REST API, в том числе и приложения из Маркета. Здесь же можно перейти к редактированию вебхука или удалить его.
Безопасность и сохранность данных
В вебхуке для вызова rest api и в адресе входящего вебхука всегда есть уникальный секретный код. В исходящем вебхуке также есть специальный секретный токен приложения. Они генерируются случайным образом при каждом создании вебхука:
Статистика
В этом разделе администратор Битрикс24 может просмотреть количество запросов по каждому вебхуку, внешней интеграции или приложению. Для удобства доступен фильтр и настройка колонок в списке вебхуков.
По умолчанию статистика показывается за последние 14 дней. Но через фильтр можно посмотреть статистику за последние 60 дней, при этом максимальный шаг в каждой выборке не должен превышать 14 дней.
Быстрая интеграция с Битрикс24 или волшебные вебхуки!
Как вы наверняка знаете, в Битрикс24 существует довольно обширный REST API, который позволяет добавлять функционал в облачный Битрикс24, а также создавать всевозможные интеграции с внешними системами. Используя методы REST вы можете создавать и модифицировать объекты CRM, задачи, публиковать сообщения в живую ленту и вообще, делать практически все, что угодно.
Но до недавнего времени существовало в этой идиллии одно небольшое «но», а именно, необходимость в реализации хитрого протокола авторизации OAuth 2.0. Несмотря на то, что этот протокол существует давно и используется многими игроками рынка, он все еще вызывает у разработчиков сложности в реализации «с нуля», а кроме того, имеет неприятное ограничение – если вам необходим постоянный автоматический обмен данными с Битрикс24 без участия пользователя, то из-за требований OAuth вам придется организовывать периодическое обновление авторизационных токенов, чтобы они «не протухли».
А ведь иногда просто надо быстренько связать конкретный Битрикс24 с конкретной внутренней системой, или скажем, отдельно взятой формой обратной связи. Или без лишних заморочек просто запостить в живую ленту портала отчеты из своей складской системы.
Я рад сообщить, что мы внедрили простой механизм интеграций с Битрикс24, который прекрасно подходит для использования in-house. Речь идет о всем известных вебхуках. А даже если и не всем известных, то многим 
Это механизм, который позволяет вам использовать практически весь наш богатый REST API, но при этом не заморачиваться с OAuth 2.0.
[spoiler]
Давайте на конкретном примере разберем, как это работает. Предположим, что у нас есть на сайте форма обратной связи по каким-то непонятным причинам еще не переведенная на прекрасные CRM-формы Битрикс24, и вместо того, чтобы использовать нормальные вещи мы все-таки хотим помучаться и допилить нашу существующую форму так, чтобы результат ее заполнения попадал в виде лида в Битрикс24.
Мы просто идем в раздел Приложения – Вебхуки, нажимаем кнопку «Добавить вебхук»
выбираем тип «Входящий вебхук» (ведь мы хотим из внешнего источника обращаться к Битрикс24, верно?) и видим форму редактирования параметров вебхука.
Указываем понятное нам самим название и описание вебхука, включаем галочку прав к нужному нам модулю Битрикс24. В данном случае нам нужен CRM, поскольку мы собираемся добавлять лиды.
После нажатия на кнопку сохранения мы обнаружим, что в форме появилась дополнительная информация
Как ни удивительно, но это все, что нам нужно.
Что значит «дернуть»? Например, это можно сделать вот так
На этом радость не заканчивается, ведь интеграция – штука двусторонняя и иногда хочется наоборот, что делать в своих или внешних системах, когда происходит некое изменение данных в Битрикс24. Ну, например, менеджер по продажам перевел сделку в Битрикс24 в нужный статус и в нашей внутренней ERP должен сформироваться наряд-заказ на запчасти из сделки.
Снова идем в Приложения – Вебхуки, но теперь добавляем «Исходящий вебхук». Форма будет отличаться, поскольку нам уже не нужно генерировать никакой ключ, зато нам нужно указать, при каком событии в Битрикс24 должен вызываться наш обработчик.
В обработчике пишем исключительно простой код – тупо логируем все, что к нам приходит.
Если теперь мы откроем любую сделку на редактирование и сохраним изменения, то обнаружим в логе вот такую историю:
Вебхуки представляются нам настолько простыми и полезными для решения оперативных вопросов, что мы включили этот функционал еще и в CRM-роботов!
Идем в настройки CRM, выбираем пункт Автоматизация и там нажимаем в кнопку «Сделки».
Чтобы не придумывать ничего сложного, воспользуемся тем же обработчиком исходящего вебхука, который у нас есть, но вызовем его в явном виде.
Нажмем кнопку «Настроить роботов», и у любого статуса сделки добавим робота, выбрав тип робота «Webhook». В открывшейся форме мы можем выбрать условия срабатывания робота, но самое главное, мы можем указать адрес обработчика и параметры, которые мы хотим в обработчик передать.
Для простоты давайте передадим туда в явном виде стадию сделки
Сохраним все это добро, перейдем в любую сделку и изменим ее стадию на ту, для которой только что сформировали робота. Сработает исходящий вебхук и в логах мы получим данные о сделке, полученные в виде параметров:
Серверная интеграция 3CX с Bitrix24
В этой статье мы рассмотрим, как выполнить интеграцию 3CX с CRM Bitrix24, используя механизм вебхуков.
Вебхук — это подписка на некоторое событие в системе, например, на поступивший вызов. Когда поступает вызов от клиента, 3CX отправляет подписавшейся системе информацию о нём с помощью HTTP-запроса. Затем уже CRM-система определяет, как использовать эту информацию.
3CX предлагает модуль интеграции с Bitrix24 непосредственно «из коробки», однако для этого необходима редакция 3CX Pro или Enterprise. Весь процесс занимает не более 5 минут!
Когда к вам поступает вызов, веб-клиент 3CX показывает небольшую карточку контакта с ссылкой на полную карточку этого контакта в CRM Bitrix24. Здесь рассматривается интеграция 3CX с Bitrix24 исключительно на стороне сервера, без использования локального модуля на стороне клиента. Такой подход имеет большое преимущество — вам не нужно обходить всех пользователей и вручную устанавливать плагины CRM-интеграции в настольные клиенты 3CX. Кроме того, теперь вы можете использовать CRM-интеграцию не только в Windows и Mac, но и в Linux, поскольку веб-клиент работает как браузерное приложение. Еще одно преимущество — новый веб-клиент спроектирован с учетом возможного расширения возможностей интерфейса. Это значит, что в будущем возможна более тесная CRM-интеграция непосредственно в интерфейсе веб-клиента.
Выполнение исходящих вызовов из интерфейса Bitrix24 выполняется с помощью специального плагина к браузеру Chrome Click2Call.
Для успешной работы интеграции при входящем вызове, входящий Caller ID должен полностью совпадать с номером соответствующего контакта в Bitrix24. Например, контакты в вашей стране (локальные) должны сохраняться в Bitrix24 в национальном формате — без международного префикса страны, а также без скобок, точек, запятых, тире и пробелов.
Настройка вебхука в Bitrix24
Зайдите в ваш портал Bitrix24, откройте меню в левом верхнем углу и перейдите в раздел Приложения > Вебхуки.
Нажмите Добавить вебхук > Входящий вебхук.
Укажите имя и описание вебхука. Установите права доступа — CRM и Списки, и сохраните изменения.
После нажатия Сохранить, появится Секретный ключ (Secret), который затем указывается в интерфейсе модуля интеграции со стороны 3CX.