--- title: Настройка description: Пошаговое руководство по настройке вебхуков IDCloud — самостоятельная настройка через портал для Web и SDK, а также настройка по клиенту для API-интеграций с использованием Check orchestration (только для Бразилии). canonical: https://developer.unico.io/ru/dual-api/developers/webhooks-and-events/setup locale: ru generated_by: markdown-export --- IDCloud поддерживает две модальности вебхуков в зависимости от способа интеграции: - **Via Portal** — для интеграций через Web и SDK. Самостоятельная настройка непосредственно в портале IDCloud. - **By client** — для API-интеграций, использующих возможность **Check orchestration** (асинхронный поток). Настраивается командой Unico. Доступно только в **Бразилии**. ### Через Портал (Web и SDK) Чтобы зарегистрировать или обновить эндпоинт вебхука, откройте портал 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 ` при каждом вызове вебхука. ****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 `); формат «только value» отправляет значение без префикса. ****Без аутентификации**** Учётные данные не передаются. Рекомендуется только для сред разработки — эндпоинты в продакшене всегда должны требовать аутентификацию. #### Состояния процесса, инициирующие уведомления В настоящее время Unico отправляет уведомление, когда процесс переходит в состояние: | Состояние | Описание | |---|---| | `PROCESS_STATE_FINISHED` | Процесс завершён — терминальное состояние, независимо от результата. | :::warning[Состояния могут изменяться] Набор состояний, о которых платформа отправляет уведомления, может измениться в будущем. Сделайте состояния, на которые реагирует ваш эндпоинт, **настраиваемыми**, чтобы добавление нового состояния не требовало повторного развёртывания вашего сервиса. ::: #### Формат запроса Доставки вебхуков — это запросы **POST** на ваш эндпоинт. Тело содержит идентификатор процесса и текущее состояние. ```json { "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0", "state": "PROCESS_STATE_FINISHED", "flow": "id" } ``` :::note[`lastEvent` и `lastEventDescription`] Эти два поля появляются в теле запроса **только если процесс истёк** до того, как пользователь завершил путь. В обычных завершённых запросах они отсутствуют. Полную схему и список возможных значений `lastEvent` см. в разделе [Типы событий](/developers/webhooks-and-events/event-types). ::: #### Ожидаемый ответ Ваш эндпоинт должен отвечать **синхронно**: - **Успех**: любой HTTP-статус в диапазоне `200`–`299`. - **Ошибка**: любой другой статус. Unico будет повторять попытки с экспоненциальным увеличением интервала вплоть до настроенного максимального числа попыток или до получения ответа `2xx`. :::tip[Отвечайте быстро] Подтверждайте получение вебхука как можно скорее (в пределах настроенного тайм-аута) и обрабатывайте тело запроса асинхронно на своей стороне. Длительная обработка внутри обработчика вебхука увеличивает вероятность тайм-аутов и лишних повторных попыток. ::: Рекомендации по идемпотентности и обработке повторных попыток см. в разделе [Безопасность](/developers/webhooks-and-events/security). ### По клиенту (API — только для Бразилии) :::info[Только для Бразилии] Вебхук по клиенту доступен исключительно для API-интеграций в Бразилии, использующих возможность **Check orchestration** — асинхронного потока, при котором результат процесса доставляется через вебхук, а не в виде синхронного ответа API. ::: Чтобы зарегистрировать или обновить ваш эндпоинт, обратитесь в команду **CS / Onboarding**. #### Обязательные параметры | Поле | Описание | |---|---| | **URL уведомлений** | Эндпоинт, на который ваша система принимает обновления статусов. Должен быть доступен по HTTPS. | | **Тип аутентификации** | Способ аутентификации Unico на вашем эндпоинте. Варианты описаны ниже. | | **Настройки повторных попыток** | Максимальное количество попыток и интервал между ними (применяется экспоненциальное увеличение интервала). | | **Ограничение параллелизма** | Максимальное количество одновременных активных доставок (максимум: **500**). | | **Тайм-аут** | Максимальное время ожидания ответа от эндпоинта, в секундах. | #### Методы аутентификации ****OAuth2**** Предоставьте: - `endpoint` вебхука - `URL` провайдера OAuth2 - `ClientId` провайдера OAuth2 - `Secret` провайдера OAuth2 Unico запросит токен доступа у провайдера OAuth2, используя клиентские учётные данные, и передаст его на ваш эндпоинт в виде Bearer-токена. ****Basic Authorization**** Предоставьте учётные данные в формате `user:pass`. Unico кодирует их в Base64 и отправляет в заголовке `Authorization: Basic ` при каждом вызове вебхука. ****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 `); формат «только value» отправляет значение без префикса. ****Без аутентификации**** Учётные данные не передаются. Рекомендуется только для сред разработки — эндпоинты в продакшене всегда должны требовать аутентификацию. #### Коды статусов Вебхук по клиенту использует **числовые коды статусов**: | Код | Описание | |---|---| | `2` | Расхождение — процесс завершён с расхождением при проверке личности. | | `3` | Завершено — процесс успешно завершён. | | `5` | Ошибка — процесс завершился из-за ошибки. | #### Формат запроса Доставки вебхуков — это запросы **POST** на ваш эндпоинт. Тело содержит идентификатор транзакции и числовой код статуса. ```json { "id": "8263a268-5388-492a-bca2-28e1ff4a69f0", "status": 3 } ``` #### Ожидаемый ответ Ваш эндпоинт должен отвечать **синхронно**: - **Успех**: любой HTTP-статус в диапазоне `200`–`299`. - **Ошибка**: любой другой статус. Unico будет повторять попытки с экспоненциальным увеличением интервала вплоть до настроенного максимального числа попыток или до получения ответа `2xx`. :::tip[Отвечайте быстро] Подтверждайте получение вебхука как можно скорее (в пределах настроенного тайм-аута) и обрабатывайте тело запроса асинхронно на своей стороне. Длительная обработка внутри обработчика вебхука увеличивает вероятность тайм-аутов и лишних повторных попыток. ::: :::warning[Доставка не менее одного раза] Платформа гарантирует доставку не менее одного раза — одно и то же уведомление может поступить несколько раз. Реализуйте идемпотентность на своей стороне, используя поле `id` для безопасной обработки дублей. Рекомендации по идемпотентности и обработке повторных попыток см. в разделе [Безопасность](/developers/webhooks-and-events/security). :::