Перейти к основному содержимому

Настройка

MarkdownChatGPTClaude

IDCloud поддерживает две модальности вебхуков в зависимости от способа интеграции:

  • Via Portal — для интеграций через Web и SDK. Самостоятельная настройка непосредственно в портале IDCloud.
  • By client — для API-интеграций, использующих возможность Check orchestration (асинхронный поток). Настраивается командой Unico. Доступно только в Бразилии.

Чтобы зарегистрировать или обновить эндпоинт вебхука, откройте портал 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.
Отвечайте быстро

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

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

Последнее обновление