Кастомный робот Битрикс24: приостановка БП до внешнего HTTP-события

Задача

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

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

бизнес-процесс
↓
кастомный робот
↓
ожидание внешнего события
↓
HTTP callback или таймаут
↓
продолжение бизнес-процесса

Как работает ожидание

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

Для каждого запуска создаётся отдельное ожидание. Внешний сервис завершает именно нужный экземпляр процесса по секретному токену.

Execute
↓
создание ожидания
↓
подписка на внешнее событие
↓
статус Executing
↓
процесс ждёт
↓
внешний callback
↓
OnExternalEvent
↓
робот завершается
↓
процесс идёт дальше

Таймаут работает как альтернативная ветка завершения ожидания: если внешний сигнал не пришёл вовремя, робот завершается по таймеру и бизнес-процесс также может продолжить работу.

Настройка действия

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

Настройка кастомного робота ожидания внешнего события в дизайнере бизнес-процессов Битрикс24 — Настройка действия: название ожидания, токен внешнего события и таймаут.

Завершение ожидания через callback

Чтобы продолжить бизнес-процесс, внешняя система отправляет HTTP POST на callback с токеном нужного ожидания.

Например:

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"result":"approved"}' \
  "$CALLBACK_URL"

В ответ callback подтверждает, что ожидание найдено и внешний сигнал принят. После этого событие передаётся в конкретный экземпляр бизнес-процесса, а робот завершает работу.

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

Продолжение бизнес-процесса

До получения callback процесс остаётся в списке активных и имеет статус выполнения.

Бизнес-процесс Битрикс24 находится в активном состоянии во время ожидания внешнего callback — Бизнес-процесс запущен и остаётся активным, пока кастомный робот ждёт внешний сигнал.

После получения callback робот завершается, и процесс переходит к следующим действиям шаблона.

Бизнес-процесс Битрикс24 завершён после получения внешнего callback — После внешнего сигнала бизнес-процесс продолжил выполнение и завершился.

Журнал ожиданий

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

Журнал завершённых внешних ожиданий бизнес-процессов Битрикс24 — Журнал показывает завершённые ожидания и результат, полученный от внешней системы.

Где это применять

Механика подходит для сценариев, где результат появляется асинхронно:

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

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