Публичный API, токены и вебхуки

У платформы есть программный контур: внешние системы взаимодействуют с ней по REST, а сценарии (workflow) принимают вызовы по вебхуку. Состав и подробное описание методов публичного API на текущий момент предоставляются по запросу: обратитесь к вашей команде сопровождения Уники — вы получите актуальную спецификацию под задачи конкретной интеграции и рекомендации по её применению. Эта глава описывает ту часть контура, которая настраивается прямо в интерфейсе: персональные API-токены и запуск сценариев по вебхуку.

Что вам понадобится

учётная запись в платформе и доступ к разделу Профиль → Безопасность;
членство в том рабочем пространстве, с которым будет работать интеграция;
право integrations:view в этом пространстве — для вызова вебхук-триггеров с авторизацией;
адрес инсталляции платформы вида https://<ваш-домен>.

Персональные API-токены в профиле: выпуск и список активных

Как выпустить и отозвать персональный API-токен

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

Откройте Профиль → Безопасность.
Нажмите Выпустить новый токен.
Скопируйте значение из блока Новый токен.
Сохраните токен в хранилище секретов на своей стороне.

Платформа добавляет токен в список активных и показывает в нём только последние четыре символа и дату выпуска. Значение — 64 шестнадцатеричных символа.

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

Чтобы прекратить доступ, нажмите Отозвать в строке нужного токена. Отзыв применяется сразу: следующий запрос с этим значением получит 401. Отозванные токены остаются в списке под свёрнутым блоком Отозванные токены с датами выпуска и отзыва — это история, а не действующий доступ.

Токены привязаны к учётной записи и живут вместе с ней. Если администратор переводит пользователя в статус disabled, платформа отзывает все его персональные токены, и интеграции на этой учётной записи останавливаются.

Как запустить сценарий по вебхуку

Сценарий получает собственный URL, если начинается с узла Webhook. Поведение узла задают три поля инспектора в редакторе сценария.

Поле	Что задаёт
Авторизация	`Bearer personal token` или режим без авторизации
Режим ответа	асинхронный или синхронный вызов
URL вебхука	адрес вида `https://<ваш-домен>/api/public/workflows/triggers/<slug>` с кнопкой Скопировать

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

curl -X POST https://<ваш-домен>/api/public/workflows/triggers/<slug> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"4172","comment":"Клиент просит перенести срок"}'

Платформа принимает тело как JSON независимо от заголовка Content-Type. В сценарии тело доступно как inputs.channel.webhook.body, рядом лежат query, headers и method.

Важно. При режиме Bearer personal token платформа проверяет не только токен, но и членство его владельца в пространстве сценария и право integrations:view.

Редактор сценария: выбран узел «Webhook», в инспекторе видны поля «Авторизация», «Режим ответа» и «URL вебхука» с кнопкой «Скопировать» — Узел «Webhook» в редакторе сценария: авторизация, режим ответа и URL вызова

Что вернётся вызывающей стороне

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

Ситуация	Ответ
Асинхронный вызов принят	`202` с полями `accepted`, `workflowRunId`, `chatId`, `eventId`
Синхронный прогон завершён	`200` с полями `ok`, `status`, `runId`, `result`
Синхронный прогон с узлом Ответ на вебхук	статус, заголовки и тело, заданные в узле
Сценарий завершился ошибкой или отменён	`200` с `ok: false`, `errorCode`, `errorMessage`
Прогон не уложился в отведённое время (по умолчанию две минуты)	`202` с `status: timeout`, ссылкой на статус в заголовке `Location` и в поле `statusUrl`
Слишком много синхронных вызовов	`429` с кодом `WORKFLOW_WEBHOOK_TRIGGER_SYNC_BUSY`

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

curl -H "Authorization: Bearer <token>" \
  https://<ваш-домен>/api/public/workflows/triggers/<slug>/runs/<id-прогона>

Незавершённый прогон отдаёт { "ok": true, "done": false, "status": "…" }, завершённый — то же тело, что и синхронный вызов.

Чем вебхук отличается от интеграции ассистента без кода

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

Как защитить программный доступ

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

Заведите под интеграцию отдельную учётную запись и включите её только в те пространства, которые ей нужны.
Соберите для неё роль под конкретные операции вместо роли администратора пространства.
Храните токен в хранилище секретов, а не в коде, конфигурации репозитория или задаче в трекере.
Меняйте токен по расписанию: выпустите новый, переключите на него интеграцию, затем отзовите старый — при таком порядке интеграция не останавливается.
Отзывайте токен сразу, если он попал в лог, переписку или скриншот.

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

Где взять полное описание методов API

Полный состав методов публичного API на текущий момент предоставляется по запросу. Обратитесь к вашей команде сопровождения Уники и опишите задачу интеграции — вы получите актуальную спецификацию нужных методов и рекомендации по авторизации и лимитам.

Почему запрос возвращает 401, хотя токен свежий

Токен не прочитан платформой. Проверьте:

заголовок передан целиком, в формате Authorization: Bearer <token>, без кавычек вокруг значения;
токен не отозван в разделе Профиль → Безопасность;
учётная запись активна: деактивация пользователя отзывает все его токены.

Почему вебхук отвечает 404

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

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

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

Что происходит с кредитами при запуске по вебхуку

Списание идёт по общим правилам: прогон сценария попадает в потребление пространства, в котором сценарий опубликован, и виден в журнале прогонов и в разделе Потребление.

Что дальше

Сценарии — как собрать сценарий с узлом Webhook и вернуть ответ вызывающей стороне.
Интеграция ассистента без кода — второй контур интеграции, в котором обработку описывает сценарий платформы.
Роли и права доступа — как собрать роль под интеграцию и выдать минимальные права.
Раздел администрирования — где находятся журналы запусков и прогонов.