Как собрать вебхук внутри бизнес-процесса Битрикс24 без внешнего сервера

Связать два портала Битрикс24 можно скриптом на отдельном сервере. Можно и без него: бизнес-процесс (БП) сам отправляет REST-запросы в другой портал, получает ответы и обновляет карточки. Всё работает внутри облака. Ниже разбираем, как устроен такой вебхук на реальном примере и где он ломается.

Почему БП, а не скрипт

• Нет инфраструктуры. Не нужны VPS, обновления, сертификаты и отдельная защита.
• Видно всем. Процесс отображается в карточке, каждый шаг пишется в журнал.
• Правится без разработчика. Логику можно поменять в визуальном редакторе.
• Права наследуются от Битрикс24. Доступ к полям проверяется системой.

Ограничение тоже есть: сложные алгоритмы в БП читаются тяжело, а отладка медленнее, чем в коде.

Анатомия адреса

Адрес вебхука собирается из частей:

{PORTAL_URL}/rest/{USER_ID}/{WEBHOOK_TOKEN}/{МЕТОД}.json?{ПАРАМЕТРЫ}

В БП части подставляются из констант, переменных и полей документа:

{=Constant:portal_url}/rest/{=Constant:user_id}/{=Constant:token}/batch.json?halt=1&cmd[lead]=crm.lead.list?filter[TITLE]={=Document:TITLE}%26SELECT[0]=ID

• {=Constant:...} — константа процесса.
• {=Variable:...} — переменная, заполненная раньше.
• {=Document:...} — поле текущего лида.
• %26 — закодированный амперсанд внутри команды.

Кодирование: главное правило

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

Пример с телефоном +79001234567:

Без второго кодирования плюс раскодируется в пробел, и номер не находится. Так же ломается значение с амперсандом: он разрывает параметры.

Это можно сделать двумя действиями подряд. Каждая переменная берёт результат предыдущей:

urlencoded_str = urlencode({Template:phone})
urlencoded_str = urlencode({Variable:urlencoded_str})

Причина: параметр вкладывается в батч и раскодируется дважды.

Цепочка batch: поиск и запуск

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

{PORTAL_URL}/rest/{USER_ID}/{WEBHOOK_TOKEN}/batch.json?halt=1
  &cmd[remote_lead]=crm.lead.list?filter[TITLE]={INN_ENCODED}%26filter[SOURCE_ID]={SOURCE_ID}%26SELECT[0]=ID
  &cmd[check_lead]=crm.lead.get?ID=$result[remote_lead][0][ID]
  &cmd[start_bizproc]=bizproc.workflow.start?TEMPLATE_ID={TEMPLATE_ID}%26DOCUMENT_ID[0]=crm%26DOCUMENT_ID[1]=CCrmDocumentLead%26DOCUMENT_ID[2]=$result[remote_lead][0][ID]%26PARAMETERS[ORIGIN_LEAD_ID]={LEAD_ID}

Что здесь важно:

• $result[remote_lead][0][ID] — ID найденного лида из первой команды.
• SELECT[0]=ID — возвращается только идентификатор, а не вся карточка. Это уменьшает ответ.
• halt=1 — при ошибке пакет останавливается. Для поиска это правильно: без найденного лида запускать процесс не нужно.
• %26 внутри cmd[...] разделяет параметры команды.

Запуск Бизнес-процесса на другом портале без батча

Если вызов один, его можно отправить напрямую. Тогда кодирование одинарное:

{PORTAL_URL}/rest/{USER_ID}/{WEBHOOK_TOKEN}/bizproc.workflow.start?TEMPLATE_ID={TEMPLATE_ID}&DOCUMENT_ID[0]=crm&DOCUMENT_ID[1]=CCrmDocumentLead&DOCUMENT_ID[2]={LEAD_ID}&PARAMETERS[email]={EMAIL_ENCODED}

Условия:

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

Запись нескольких значений в карточку

Телефоны, email и сайты в Битрикс24 — множественные поля. Чтобы добавить новое значение первым и не затереть старые, в БП собирают команды вида:

crm.lead.update?ID={LEAD_ID}%26fields[PHONE][0][VALUE]={двойное кодирование}%26fields[PHONE][0][VALUE_TYPE]={тип}

Порядок работы в бизнес-процессе:

1. Перебираем существующие значения в цикле ForEach.
2. Для каждого значения накапливаем индекс (var1, var2), чтобы не путать позиции.
3. Отдельно собираем команды удаления старых значений по ID и команды добавления новых.
4. Отправляем всё одним батчем с halt=0. При записи лучше сохранить частичный результат, чем остановиться посередине.

Отладка

1. Тестируйте на одном лиде. Не запускайте процесс на всей базе.
2. Пишите собранный адрес в журнал, но маскируйте токен. Иначе журнал станет утечкой доступа.
3. Проверяйте кодирование на трудных значениях: с плюсом, пробелом, амперсандом, кавычками.
4. Сохраняйте ответ портала в переменную или комментарий, иначе не поймёте, что вернулось.

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

• Токен в константах виден всем, кто может редактировать бизнес-процесс. Ограничьте круг редакторов.
• Вебхук создавайте от технического пользователя, с минимальным набором методов.
• Если токен попал в журнал, переписку или скриншот, перевыпустите его и обновите константы.

Идемпотентность

Процесс может запускаться повторно: при изменении лида, ручном перезапуске или сбое. Без защиты данные задвоятся. Простой способ — поле-флаг «Уже запускался?»: процесс проверяет его в начале и ставит в конце.

Что здесь не очевидно

• Двойное кодирование и %26 внутри батча. Без них запрос тихо возвращает не то.
• Цепочки $result[...] и частичный успех батча.
• Сравнение значений с разным форматом: телефон с кодом страны и без, email в разном регистре, сайт со слэшем и без.
• Одновременная работа нескольких порталов с разными правами и версиями.

Всё это выглядит понятным, пока не столкнётесь с конкретной задачей.

Если нужно под вашу задачу

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