Настройка

Markdown

Чтобы зарегистрировать или обновить эндпоинт вебхука, откройте портал IDCloud и перейдите в раздел Настройки > Webhook.

Обязательные параметры

Поле	Описание
URL уведомлений	Эндпоинт, на который Unico будет отправлять уведомления о событиях. Должен быть доступен по HTTPS.
Тип аутентификации	Способ аутентификации Unico на вашем эндпоинте. Варианты описаны ниже.
Настройки повторных попыток	Максимальное количество попыток и интервал между ними (применяется экспоненциальное увеличение интервала).
Ограничение параллелизма	Максимальное количество одновременных активных доставок (максимум: 500).
Тайм-аут	Максимальное время ожидания ответа от эндпоинта, в секундах.
Уведомляемые статусы	Набор состояний процесса, при которых отправляется уведомление. В настоящее время зафиксировано значение PROCESS_STATE_FINISHED; на данный момент не настраивается.

Методы аутентификации

OAuth2

Предоставьте:

• endpoint вебхука
• URL провайдера OAuth2
• ClientId провайдера OAuth2
• Secret провайдера OAuth2

Unico запросит токен доступа у провайдера OAuth2, используя клиентские учётные данные, и передаст его на ваш эндпоинт в виде Bearer-токена.

Basic Authorization

Предоставьте учётные данные в формате user:pass. Unico кодирует их в Base64 и отправляет в заголовке Authorization: Basic <encoded> при каждом вызове вебхука.

API Key

Поддерживаются два формата. Строка разделяется по первому двоеточию:

• header:value — задаёт пользовательское имя заголовка. Примеры:
  • X-API-Key:abc123 → X-API-Key: abc123
  • Authorization:Bearer abc123 → Authorization: Bearer abc123
• только value (без двоеточия) — значение отправляется в заголовке Authorization без префикса схемы. Пример: abc123 → Authorization: abc123.

Используйте формат header:value, когда нужна схема Bearer (например, Authorization:Bearer <token>); формат «только value» отправляет значение без префикса.

Без аутентификации

Учётные данные не передаются. Рекомендуется только для сред разработки — эндпоинты в продакшене всегда должны требовать аутентификацию.

Состояния процесса, инициирующие уведомления

В настоящее время Unico отправляет уведомление, когда процесс переходит в состояние:

Состояние	Описание
PROCESS_STATE_FINISHED	Процесс завершён — терминальное состояние, независимо от результата.

Состояния могут изменяться

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

Формат запроса

Доставки вебхуков — это запросы POST на ваш эндпоинт. Тело содержит идентификатор процесса и текущее состояние.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}

lastEvent и lastEventDescription

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

Ожидаемый ответ

Ваш эндпоинт должен отвечать синхронно:

• Успех: любой HTTP-статус в диапазоне 200–299.
• Ошибка: любой другой статус. Unico будет повторять попытки с экспоненциальным увеличением интервала вплоть до настроенного максимального числа попыток или до получения ответа 2xx.

Отвечайте быстро

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

Рекомендации по идемпотентности и обработке повторных попыток см. в разделе Безопасность.