B2BPRO.KZ | Рекламное агентство в Алматы

REST API и вебхуки Битрикс24 простыми словами: что это и когда нужны

Обложка: Вебхуки простыми словами. Типографская обложка рубрики Битрикс24, входящие и исходящие вебхуки

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

Обычно к этой теме приходят с конкретной задачей: передавать заявки с сайта в CRM, сообщать бухгалтерской программе об оплаченном счете или выгружать отчет в таблицу. Ниже объясняем без кода, что такое входящий и исходящий вебхуки, чем они отличаются, кто и как их создает, как не потерять секретный ключ и в каких случаях вебхука уже мало.

Что такое REST API Битрикс24 простыми словами

REST API — это договоренность о том, как одна программа просит другую выполнить действие по интернету. В Битрикс24 у каждого действия есть имя метода: добавить лид, получить сделку, создать задачу, отправить сообщение в чат. Программа вызывает метод, передает параметры и получает ответ в формате JSON.

Представьте портал как офис с охраной. Методы — это услуги, которые офис готов выполнять для посетителей: принять документ, выдать справку, записать на прием. Вебхук — пропуск, выданный конкретному сотруднику и действующий только для определенных дверей. Все, что вы можете сделать с портала через интерфейс, внешняя система тоже может сделать, но только в рамках выданного пропуска.

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

Входящий вебхук: что это и как работает

Входящий вебхук — это ссылка, по которой внешняя система вызывает методы REST API от имени сотрудника, создавшего вебхук. Слово «входящий» означает, что данные входят в Битрикс24 или запрашиваются из него по инициативе внешней программы.

Ссылка состоит из нескольких частей. Это адрес вашего портала, путь /rest, номер сотрудника, который создал вебхук, секретный код и имя метода. Если собрать их вместе, получится адрес вида «портал/rest/1/секретный-код/имя-метода». Секретный код в этой ссылке заменяет логин и пароль, поэтому к ссылке нужно относиться как к ключу от сейфа.

Главные свойства входящего вебхука, которые подтверждает официальная документация по вебхукам:

  • права вебхука равны правам сотрудника, который его создал, плюс ограничены списком выбранных областей доступа (scope);
  • создать входящий вебхук может администратор или сотрудник, которому администратор дал такое право;
  • для вебхука можно указать дату окончания: после нее запросы перестанут проходить и вернут ошибку авторизации;
  • часть методов через вебхук недоступна, потому что требует контекста приложения. Например, встраивание виджетов и некоторые сценарии чат-ботов.

Три примера задач, для которых входящий вебхук подходит лучше всего. Первая: форма на сайте создает в CRM лид или сделку с данными посетителя. Вторая: скрипт раз в сутки собирает список сделок и пишет его в таблицу для руководителя. Третья: бухгалтерская программа после оплаты находит сделку и меняет ее стадию.

Исходящий вебхук: чем он отличается от входящего

Исходящий вебхук — это обратное направление: Битрикс24 сам отправляет сообщение на ваш адрес, когда в портале что-то произошло. Вы выбираете событие, например изменение сделки, и указываете адрес обработчика. Как только событие наступает, портал отправляет на этот адрес POST-запрос.

Важный нюанс, из-за которого новички часто путаются: исходящий вебхук не выполняет метод и не присылает все данные объекта. Обработчик получает название события, идентификатор объекта и служебные поля авторизации. Если нужны подробности, например сумма сделки и ответственный, обработчик делает дополнительный запрос через входящий вебхук или приложение. В документации Битрикс24 в качестве типового сценария как раз описано: взять идентификатор сделки из события и запросить ее полные данные отдельным методом.

Три примера для исходящего вебхука. Первый: менеджер перевел сделку на стадию «Оплачено», внешняя система получает сигнал и запускает отгрузку. Второй: в портале создан новый контакт, и его данные уходят в рассылочный сервис. Третий: изменилась стадия сделки, а ответственному в мессенджер приходит уведомление, которое нельзя настроить штатными роботами.

Сравнение: входящий и исходящий вебхук

Параметр Входящий вебхук Исходящий вебхук
Кто инициирует обмен Внешняя система обращается к порталу Портал сообщает внешней системе о событии
Что нужно для работы Ссылка с секретным кодом Публичный адрес обработчика и токен для проверки
От чьего имени работает От сотрудника, создавшего вебхук Передает событие, сам методы не вызывает
Типовая задача Создать лид, прочитать сделки, изменить стадию Узнать о смене стадии, создании контакта, обновлении сделки
Главный риск Утечка ссылки с секретным кодом Обработчик недоступен из интернета или не проверяет подлинность

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

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

Входящий вебхук создают в разделе «Разработчикам» портала. По документации порядок такой:

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

Если пункта «Входящий вебхук» в списке нет, значит, право на создание вебхуков вам не выдано. Администратор открывает его в настройках портала: «Настройки», затем «Настройки Битрикс24», раздел «Безопасность», вкладка «Интеграции Битрикс24», поле «Кому разрешить создавать входящие вебхуки». Там можно выбрать всех сотрудников или только отдельных людей. Мы советуем второй вариант: чем меньше людей умеют выпускать ключи к данным компании, тем проще за ними следить.

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

Исходящий вебхук создают там же, в разделе «Разработчикам»: «Готовые сценарии», «Другое», «Исходящий вебхук». Нужно указать адрес вашего обработчика и выбрать событие, на которое он будет реагировать, затем нажать «Создать» и проверить вызов после тестового изменения данных.

У исходящего вебхука есть условия, которые стоит проверить до начала работ:

  • адрес обработчика должен быть публичным: localhost, адреса из локальной сети и обработчики с самоподписанным сертификатом не подойдут;
  • обработчик должен принимать POST-запросы;
  • в коробочной версии Битрикс24 нужна активная лицензия, а также открытые сетевые доступы;
  • на демонстрационных режимах исходящий вебхук недоступен.

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

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

Вебхук дает ровно те права, что у сотрудника, создавшего его, в пределах выбранных областей доступа. Поэтому первый принцип безопасности: не создавайте вебхуки от имени администратора, если задаче хватит прав менеджера. Допустим, нужно только читать список сделок. Тогда создайте вебхук с областью доступа CRM, а выпускать его лучше от имени отдельного технического сотрудника с минимально нужными правами. Список областей доступа и методов приведен в справочнике прав REST API.

Второй принцип: ссылку вебхука не передают посторонним и не публикуют в коде, который виден посетителям сайта. Именно так секретные коды чаще всего и утекают. Ссылку вставили в JavaScript формы на сайте, и любой, кто откроет код страницы, получил доступ к CRM в пределах прав вебхука. Правильная схема: форма отправляет данные на ваш сервер, а уже сервер обращается к вебхуку.

Третий принцип: у секретного кода есть владелец. По документации, секретный код доступен только сотруднику, который создал вебхук. Если администратор отредактирует чужой вебхук, код обновится, а владельцем станет администратор. Значит, после правки надо обязательно заменить ссылку в той системе, которая ее использует, иначе обмен остановится.

Четвертый принцип: ведите реестр. Заведите таблицу, где для каждого вебхука записано, кто создал, для чего, в какой системе используется и когда проверялся. Через год, когда сотрудник уволится или система сменится, вы быстро поймете, что можно отключить. На проектах B2BPRO.KZ мы чаще всего встречаем порталы, где десяток вебхуков создан давно, никто не помнит для чего, и отключить их страшно.

Как выглядит типовая интеграция от начала до конца

Возьмем иллюстративный пример: интернет-магазин хочет, чтобы оплаченный заказ автоматически попадал в CRM как сделка, а при смене стадии на «Отгружено» клиент получал сообщение. Это придуманный сценарий, но по логике он повторяет большинство реальных задач.

  1. Администратор разрешает техническому сотруднику создавать входящие вебхуки и ограничивает права этого сотрудника нужным разделом CRM.
  2. Сотрудник создает входящий вебхук, проверяет в генераторе запросов метод создания сделки и сохраняет ссылку в настройках сервера магазина.
  3. При оплате заказа сервер магазина вызывает метод и получает в ответе идентификатор новой сделки. Его записывают в заказ, чтобы потом связать обе записи.
  4. Для обратного направления создают исходящий вебхук на событие изменения сделки. Адрес обработчика — страница на том же сервере, токен сохранен в настройках.
  5. Когда менеджер двигает сделку, обработчик получает событие и идентификатор, проверяет токен и запрашивает данные сделки через входящий вебхук. Если стадия «Отгружено», отправляет клиенту сообщение.
  6. Все вебхуки заносят в реестр, а в проверку работоспособности добавляют тестовый заказ раз в неделю.

Обратите внимание, сколько здесь решений, не связанных с программированием: кто владелец вебхука, какие права, где хранится ссылка, кто отвечает за проверку. Именно эти решения определяют, проработает ли интеграция год или сломается через месяц.

Частые ошибки при работе с вебхуками

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

  • Вебхук создан от личной учетной записи руководителя. Когда сотрудник уходит или меняет роль, права меняются, и интеграция останавливается без предупреждения. Лучше выпускать вебхуки от технического пользователя.
  • Область доступа выбрана «на всякий случай» шире нужной. Чем больше прав, тем дороже последствия утечки.
  • Ссылка лежит в открытом виде. Ее отправили в чате подрядчику, вставили в письмо или разместили в клиентском коде. Любой, кто увидит такую ссылку, получит ключ.
  • Исходящий вебхук принимает запросы без проверки токена. Тогда обработчик отвечает на любые сообщения, в том числе поддельные.
  • Нет плана на случай ошибки. Если Битрикс24 недоступен несколько минут, а обработчик не умеет повторять запросы, данные теряются. Для важных процессов нужна очередь или хотя бы периодическая сверка.
  • Никто не отвечает за интеграцию. Она работает, пока не сломается, а когда ломается, выясняется, что человек, который ее делал, давно ушел.

Что делать, если интеграция перестала работать

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

Отдельная тема — частота запросов. У REST API есть ограничения на нагрузку, и массовые скрипты упираются в них раньше, чем в права. Что именно нужно учесть, мы описали в статье про ограничения REST API Битрикс24. А чтобы молчаливые остановки не оставались незамеченными, заведите проверку, как в материале про мониторинг интеграций.

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

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

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

Подробнее о локальных приложениях можно прочитать в документации по локальным приложениям. Для компании с одним порталом и несколькими интеграциями вебхука обычно хватает, и усложнять схему ради красоты не нужно.

Вебхук, готовый коннектор или разработка: как выбрать

Прежде чем заказывать разработку, ответьте на три вопроса. Есть ли у вашей системы готовое подключение к Битрикс24? Если есть, используйте его: у такого решения есть поддержка и обновления. Достаточно ли простого сценария, когда одно событие приводит к одному действию? Тогда помогут встроенные роботы и бизнес-процессы без кода. И только если сценарий выходит за эти рамки, нужен вебхук с обработчиком или приложение. Обзор способов подключения и их границ есть в статье «Интеграции Битрикс24: что можно подключить к CRM и как выбрать способ связи».

Если у вас нет своего программиста, интеграцию можно заказать у партнера. B2BPRO.KZ — официальный партнер Битрикс24 в Казахстане: мы настраиваем обмен между порталом, сайтом и учетными системами, а также берем на сопровождение уже работающие интеграции. Оставить заявку на внедрение и настройку Битрикс24 можно на странице услуги, а если обмен уже сломался, поможет техподдержка Битрикс24 24/7.

Контрольный список перед запуском вебхука

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

  • Метод доступен по выбранной области доступа, а у создавшего вебхук сотрудника есть права на нужный объект.
  • В портале включен доступ к REST API, запросы идут по HTTPS.
  • Для вебхука задан срок действия или записано, что он бессрочный, и это осознанный выбор.
  • Ссылка вебхука хранится на сервере, а не в коде страницы.
  • Обработчик исходящего вебхука сравнивает токен из запроса с сохраненным.
  • Вебхук занесен в реестр: владелец, назначение, система, дата проверки.
  • Есть человек, который узнает, если обмен остановится.

Частые вопросы

Чем вебхук отличается от REST API?

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

Можно ли использовать вебхук без программиста?

Да, но только для простых случаев. Создать вебхук и проверить вызов метода в генераторе запросов может любой сотрудник с нужными правами. Однако обработчик, который будет принимать события или вызывать ссылку по расписанию, обычно требует разработки. Для простых цепочек лучше использовать роботов или готовые коннекторы.

Что будет, если ссылка входящего вебхука попала к посторонним?

Тот, у кого оказалась ссылка, сможет вызывать методы в рамках прав вебхука. Поэтому ссылку нужно сразу заменить: создайте новый вебхук, подставьте его в систему и удалите скомпрометированный. Чтобы последствия были меньше, выдавайте вебхукам только нужные области доступа.

Кто может создавать вебхуки в Битрикс24?

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

Работают ли вебхуки в коробочном Битрикс24?

Да, но у исходящего вебхука в коробочной версии есть условия: нужна активная лицензия и открытые сетевые доступы. Обработчик должен быть доступен из внешней сети и принимать POST-запросы. На демонстрационных режимах исходящий вебхук недоступен.

Нужно ли платить за вебхуки?

За сам механизм вебхуков отдельная плата в документации не указана. Расходы появляются там, где нужна разработка обработчика, хостинг для него и сопровождение. Условия лицензии на вашем тарифе стоит уточнять в личном кабинете или у партнера.

Техподдержка Битрикс24

Обмен через вебхук остановился?

Проверим права, срок действия вебхука и доступность обработчика, затем восстановим обмен. Мы официальный партнер Битрикс24 в Казахстане, линия работает круглосуточно.

Написать в поддержку

Прокрутить вверх