Вебхуки и REST API Битрикс24: что можно автоматизировать без разработчика

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

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

REST API - это набор адресов, по которым можно попросить Битрикс24 что-то сделать. Каждый адрес соответствует методу: crm.deal.add создаёт сделку, crm.contact.list возвращает список контактов, tasks.task.add создаёт задачу. Запрос отправляется обычным HTTP-обращением, ответ приходит в формате JSON.

Вебхук бывает двух видов, и их постоянно путают.

Входящий вебхук - ссылка, по которой внешняя система обращается к Битрикс24. Вы даёте эту ссылку сервису, и он создаёт или читает данные на вашем портале.

Исходящий вебхук - наоборот. Битрикс24 сам отправляет данные на указанный вами адрес, когда происходит событие: создана сделка, изменена стадия, добавлен контакт.

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

Как создать вебхук: пошагово

1. Откройте раздел для разработчиков. В большинстве порталов путь такой: левое меню, «Приложения», затем «Разработчикам». В части конфигураций пункт называется «Ресурсы разработчика».
2. Выберите создание входящего вебхука.
3. Задайте описание, чтобы через полгода понимать, кому эта ссылка выдана: «Выгрузка сделок в таблицу», «Формы с сайта».
4. Отметьте права доступа. Выдавайте только нужные: CRM, задачи, пользователи, диск. Не ставьте все галочки подряд.
5. Сохраните. Портал покажет готовую ссылку вида https://ваш-портал.bitrix24.ru/rest/1/токен/.
6. Скопируйте ссылку и сохраните её в надёжном месте. Она равносильна паролю от данных портала в пределах выданных прав.

Проверить работу можно прямо в браузере: добавьте к ссылке метод, например profile, и откройте адрес. Если вернулся JSON с вашим профилем, вебхук работает.

Важный нюанс: вебхук работает от имени того сотрудника, который его создал, и видит ровно то, что видит этот сотрудник. Создавайте вебхуки от учётной записи с нужным уровнем доступа, а не от личного аккаунта сотрудника, который может уволиться.

Методы, которые нужны чаще всего

Метод получения списка полей заслуживает отдельного внимания. Прежде чем что-то создавать через API, вызовите crm.deal.fields или аналогичный метод для нужной сущности. Вы увидите реальные коды полей, включая пользовательские вида UF_CRM_.... Без этого вы будете угадывать названия и получать ошибки.

Что реально сделать без разработчика

1. Приём заявок с сайта в CRM

Если на сайте своя форма, её можно связать с Битрикс24 без интеграции. Данные формы отправляются на вебхук с методом crm.lead.add, и заявка появляется в CRM с источником и UTM-метками. На большинстве конструкторов сайтов и в сервисах автоматизации это настраивается визуально, без кода.

Что учесть: заполняйте поле источника, иначе через месяц вы не поймёте, откуда пришли лиды.

2. Выгрузка данных в Google Таблицы

Классическая задача: руководителю нужен свой отчёт, которого нет в стандартной аналитике. Через сервис автоматизации или скрипт таблицы вызывается crm.deal.list с фильтром по датам, данные ложатся в лист, дальше строится сводная таблица и график.

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

3. Уведомления во внешние каналы

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

4. Массовое обновление данных

Нужно проставить источник у 2000 старых лидов или перенести значение из одного поля в другое. Через пакетный метод batch это делается скриптом на 20 строк или через сервис автоматизации с обходом списка. Ручная правка заняла бы неделю.

5. Импорт базы из таблицы

Список из 5000 контрагентов в Excel превращается в контакты и компании CRM через последовательные вызовы crm.company.add и crm.contact.add. Плюс сравнение с существующими записями, чтобы не создать дубли.

6. Синхронизация с простым внешним сервисом

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

7. Автоматическое создание задач по расписанию

Скрипт по расписанию вызывает tasks.task.add и создаёт задачи по сложным правилам, которых нет в штатных регулярных задачах: например, задача создаётся только в последний рабочий день месяца. Про работу с задачами есть отдельный материал: Управление задачами в Битрикс24.

Где заканчиваются возможности без программиста

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

Обработка ошибок. Что делать, если внешний сервис недоступен, а сделку уже создали? Как повторить неудачный запрос? Как не создать дубль при повторе? Без этой логики интеграция работает до первого сбоя.

Лимиты API. У портала есть ограничения на частоту запросов. При превышении запросы отклоняются. Нужны очереди, паузы и пакетные запросы.

Большие объёмы. Выгрузить 200 000 сделок одним запросом нельзя. Нужна постраничная обработка с учётом смещения и корректной работой при изменении данных во время выгрузки.

Двусторонний обмен. Запись изменили и в Битрикс24, и во внешней системе. Чья версия побеждает? Без явного правила данные разъезжаются.

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

Безопасность и аудит. Кто и когда пользовался вебхуком, что менялось, как отозвать доступ при увольнении.

Если задача попадает хотя бы в два пункта из списка, дешевле сразу отдать её разработчику, чем чинить самодельную связку каждую неделю.

Вебхук или приложение: что выбрать

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

Безопасность: правила, которые нельзя нарушать

1. Вебхук равен паролю. Кто угодно с этой ссылкой получит доступ к данным в пределах выданных прав. Не отправляйте её в общих чатах и не храните в открытых документах.
2. Минимальные права. Нужно создавать сделки - выдайте права только на CRM. Не отмечайте все скоупы «на всякий случай».
3. Отдельный вебхук на каждую интеграцию. Тогда при компрометации или отключении сервиса вы отзываете один доступ, а не ломаете всё сразу.
4. Не встраивайте вебхук в код фронтенда. Ссылка в JavaScript на сайте видна любому посетителю. Запросы должны идти с сервера.
5. Ревизия раз в квартал. Откройте список вебхуков и удалите те, назначение которых никто не помнит.
6. Служебная учётная запись. Создавайте вебхуки от специально заведённого пользователя, а не от личного аккаунта сотрудника.
7. Логи. Если связку делает подрядчик, требуйте логирование запросов и ошибок. Без логов диагностика сбоя превращается в гадание.

Типичные ошибки

Угаданные коды полей. Пользовательские поля имеют коды вида UF_CRM_1712345678, а не человеческие названия. Всегда получайте список полей методом fields перед разработкой.

Игнорирование ответа. Скрипт отправил запрос и не проверил результат. Битрикс24 вернул ошибку, никто не заметил, данные не создались.

Отсутствие проверки дублей. Каждая отправка формы создаёт новый контакт. Через месяц в базе три записи на одного клиента. Перед созданием ищите существующего клиента по телефону или почте.

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

Вебхук уволившегося сотрудника. Учётную запись отключили, интеграция встала, причину искали два дня.

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

С чего начать, если вы не программист

1. Создайте вебхук с правами только на чтение CRM.
2. Откройте в браузере адрес вебхука с методом crm.deal.list и посмотрите на структуру ответа.
3. Вызовите crm.deal.fields и выпишите коды полей, которые вам нужны.
4. Соберите первую простую связку: выгрузку сделок в таблицу по расписанию.
5. Убедитесь, что данные совпадают с тем, что видно в интерфейсе.
6. Только после этого переходите к записи данных в портал, и сначала на тестовых записях.

Такой порядок исключает главный риск новичка: испортить боевые данные экспериментальным скриптом.

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

Чем вебхук отличается от приложения?

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

Нужен ли платный тариф для работы с REST API?

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

Есть ли ограничения на количество запросов?

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

Можно ли через API изменить интерфейс Битрикс24?

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

Как понять, какой метод мне нужен?

Откройте официальную документацию REST API Битрикс24 и найдите раздел по нужной сущности: CRM, задачи, пользователи, диск. Названия методов строятся логично: сущность плюс действие, например crm.company.update. Список полей всегда узнавайте методом fields у той же сущности.

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

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

Что дальше

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

Мы в Aventra делаем и то, и другое: от простой связки на вебхуках до собственных приложений и обменов с 1С, складом и отраслевыми системами. Смотрите услуги по интеграциям, разработке приложений и внутренних систем и автоматизации процессов. Если вы только планируете доработку, полезно заранее понимать структуру бюджета: об этом статья Сколько стоит доработка Битрикс24. Напишите нам, оценим задачу бесплатно.