Внешнее действие

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

Настройка через интерфейс

В режиме Проектирование создайте или откройте кнопку процесса, нажмите Добавить действие и выберите Внешнее действие.
В карточке действия укажите HTTPS-адрес внешнего сервиса.
Если данные callback должны изменить карточку, нажмите Добавить сопоставление. Для каждого значения укажите:
- Путь в callback data — путь внутри объекта data, например result.comment для значения data.result.comment;
- Куда записать значение — новый комментарий, системное поле карточки (Название, Описание, Срок или Причина блокировки) либо пользовательское поле доступной доски;
- Что делать при ошибке данных callback — пропустить только это сопоставление либо завершить весь запуск с ошибкой.
Сохраните кнопку и сразу скопируйте показанный signing secret: повторно посмотреть его нельзя. Обычное сохранение настройки secret не меняет.

Путь в callback data состоит из разделённых точками ключей объекта data. Каждый ключ может содержать латинские буквы, цифры, _ и -; массивы и выражения JSONPath не поддерживаются. Выбранное поведение при ошибке применяется, если пути нет либо найденное значение нельзя записать в целевое поле. В режиме ошибки Noiro проверяет все сопоставления до изменения карточки.

Как заменить signing secret

Откройте кнопку процесса, найдите внешнее действие, нажмите Перегенерировать secret и подтвердите замену. Старый secret сразу перестанет принимать callback, включая уже ожидающие запуски.
Сразу сохраните новый secret, который покажет Noiro: повторно посмотреть его нельзя.

Единая подпись

И Noiro, и ваш сервис используют один и тот же способ подписи сырого тела запроса:

X-Noiro-Timestamp: 2026-05-03T12:00:00Z
X-Noiro-Signature: v1=<hmac_sha256(signing_secret, timestamp + "." + raw_body)>
Content-Type: application/json

На принимающей стороне соберите строку timestamp + "." + raw_body, вычислите HMAC-SHA256 с сохранённым signing secret и сравните результат с частью после v1= через constant-time compare. Также отклоняйте слишком старые timestamp.

Как Noiro отправляет запрос

При нажатии кнопки Noiro отправляет POST на настроенный URL. В теле запроса есть:

runId — идентификатор запуска внешнего действия;
automationId — идентификатор автоматизации;
callbackUrl — адрес для результата;
card — карточка, по которой нажали кнопку;
customFieldValues — значения пользовательских полей карточки.

Endpoint должен быстро принять запрос и вернуть точное подтверждение:

HTTP/1.1 200 OK
Content-Type: text/plain

OK

После такого ответа Noiro считает, что внешний сервис принял запуск в обработку, и ждёт callback. Тело ACK никогда не применяется к карточке через сопоставления: они читают только объект data подписанного callback. Долгую работу нужно выполнять после ACK и возвращать результат отдельным callback.

При временных ошибках доставки Noiro делает несколько повторных попыток. Все попытки одного запуска используют один стабильный runId, поэтому внешний сервис обязан дедуплицировать работу по этому идентификатору. Повторяются сетевые ошибки, 429 и 5xx. Для 429 Noiro использует заголовок Retry-After, если он передан. Ошибки 4xx, включая 408 Request Timeout, не повторяются: endpoint должен быстро принять запрос и вернуть 200 OK. Если после попыток запрос всё равно не принят, Noiro сам помечает запуск внешнего действия как неуспешный.

Что происходит с callback

Отправьте POST на полученный callbackUrl. Callback подписывается тем же способом и принимает JSON с полями data и fileIds:

{
  "data": {
    "result": {
      "comment": "Клиент просит срочный ответ"
    },
    "priority": "high"
  },
  "fileIds": [
    "018f0d1e-7d43-7c42-a6b5-2d4c7c2b2c31"
  ]
}

Если callback прошёл проверку и результат удалось применить, запуск становится успешным. Карточка изменяется согласно сопоставлениям, настроенным в интерфейсе; без сопоставлений данные callback карточку не меняют.

Ответ запуска кнопки содержит automationRuns с идентификатором, сроком и текущим статусом каждого внешнего действия. Актуальный статус доступен через GET /api/workflow-automation-runs/{runId}. Если callback не пришёл до expiresAt, статус становится failed, а поле error объясняет таймаут. Повторный, просроченный или инвалидированный ротацией callback получает 409 Conflict и не меняет карточку повторно.

Если внешний сервис должен прикрепить файлы, он передаёт только fileIds уже загруженных файлов. Callback не принимает binary/base64-контент и не скачивает файлы по внешним ссылкам.