Вебхук

Вебхук — это способ, с помощью которого IDCloud автоматически сообщает вашей системе о том, что произошло в процессе верификации личности. Вместо того чтобы ваша система постоянно спрашивала «уже готово?», IDCloud вызывает ваш API в момент возникновения события.

На этом экране вы указываете адрес вашего API, способ аутентификации IDCloud при обращении к нему и что происходит, если он не отвечает.

информация

Для кого это: для клиентов, которые хотят автоматически получать результаты процесса без опроса (polling). Применимо как к интеграциям byUnico, так и к интеграциям byClient.

Что изменится в вашей системе: теперь она получает уведомление при каждом изменении состояния, вместо необходимости опрашивать IDCloud.

Где это найти: портал IDCloud → боковая панель Settings → вкладка Webhook.

До появления этого экрана любое изменение вебхука требовало обращения в поддержку — около 30 тикетов в месяц только по этому вопросу. Теперь вы делаете это самостоятельно, за несколько минут, как в Staging, так и в Production.

Прежде чем начать

Права доступа

Вашему пользователю нужен профиль Configurator — тот же самый, что даёт доступ к Journey Customization. Если вкладка Webhook не отображается, обратитесь к администратору вашего аккаунта.

Как применяется конфигурация

Область действия	Один вебхук на тенант и филиал. Списка нет: если вебхук уже настроен, он редактируется, а не дублируется.
Раздельные окружения	Портал Staging настраивает вебхук UAT; портал Production настраивает Production. Настройка одного не влияет на другой.
Когда вступает в силу	Сразу после сохранения.
Безопасность секрета	Секрет шифруется и больше никогда не показывается в открытом виде. На экране он всегда замаскирован.

Что подготовить

• HTTPS-адрес (URL) вашего API, который будет получать уведомления. Он должен быть доступен и принимать запросы ещё до того, как вы сохраните настройки.
• Учётные данные (credentials), которые ожидает ваш API, в зависимости от выбранного метода аутентификации (см. шаг 3).
• Если у вашего API есть ограничение по пропускной способности — количество запросов в секунду, которое он поддерживает.

Что решить заранее

Два технических решения зависят от того, кто обслуживает ваш API, а не от того, кто работает с порталом. Стоит согласовать это до открытия экрана:

• Какой метод аутентификации требуется вашему API.
• Будете ли вы настраивать повторные попытки (retries) или оставите значения по умолчанию. Значения по умолчанию подходят для большинства случаев.

Шаг за шагом

Шаг 1 — Откройте вкладку Webhook

В портале IDCloud нажмите на значок шестерёнки (Settings) в боковой панели и выберите вкладку Webhook.

Если у вас пока не настроен вебхук, на экране отображается надпись «No webhooks created» и кнопка Create webhook. Если вебхук уже есть, экран показывает карточку Your webhook с эндпоинтом, типом аутентификации и замаскированным секретом, а также кнопку Configure webhook для его редактирования.

Карточка «Your webhook» с эндпоинтом, типом аутентификации и замаскированным секретом.

Шаг 2 — Введите URL вашего API

Нажмите Create webhook (или Configure webhook, если он уже существует) и заполните поле Client URL (Endpoint) в разделе «Client information».

Это адрес, на который IDCloud будет отправлять уведомления. Он должен использовать протокол HTTPS.

Указывайте адрес, который уже работает. IDCloud начинает обращаться к этому URL сразу после сохранения. Если адрес пока не существует, первые уведомления завершатся ошибкой и израсходуют все повторные попытки ещё до того, как ваша команда это заметит.

Поле Endpoint с текстом подсказки о требовании HTTPS.

Шаг 3 — Выберите способ аутентификации IDCloud в вашем API

В разделе «Authentication» выберите Authentication type. Доступны четыре варианта, и для каждого требуются разные поля:

Тип	Отображаемые поля	Когда использовать
None	нет	Ваш API не требует аутентификации. Используйте этот вариант только если у него есть какая-то другая защита — без аутентификации любой, кто узнает URL, может отправлять на него данные
API Key	Secret	Ваш API проверяет фиксированный ключ
Basic Auth	Secret	Ваш API использует имя пользователя и пароль в стиле HTTP Basic
OAuth 2.0	Auth URL, Client ID, Secret	Ваш API требует токен. IDCloud получает токен по этому URL и самостоятельно обновляет его

Для OAuth 2.0 поле Auth URL — это адрес, с которого IDCloud получает токен, а не URL, получающий уведомления. Это разные адреса, и их перепутать — самая частая ошибка на этом экране.

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

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

Поле Authentication type и соответствующие поля учётных данных.

Шаг 4 — При необходимости настройте повторные попытки

Раздел Retry configuration является необязательным и по умолчанию выключен. Включайте его только если нужно изменить поведение по умолчанию.

При включении становятся доступны шесть полей:

Поле	Что оно контролирует	По умолчанию
Maximum retries	Сколько раз IDCloud повторит попытку, прежде чем сдаться	—
Rate limit (req/s)	Максимальное количество уведомлений в секунду. Снизьте значение, если у вашего API ограниченная пропускная способность	—
Minimum time (s)	Минимальный интервал между попытками	2 с
Maximum time (s)	Максимальный интервал между попытками	10 с
Maximum duration (s)	Сколько времени ждать на каждую попытку, прежде чем считать её неудачной	2 с
Maximum doublings	Коэффициент роста интервала между попытками (backoff)	5

Итоговое поведение таково: IDCloud делает попытку, ждёт minimum time, делает следующую попытку и продолжает увеличивать интервал в соответствии с maximum doublings до значения maximum time — повторяя это до maximum retries. Каждая отдельная попытка завершается по истечении maximum duration.

Перед тем как менять что-либо ещё, настройте Rate limit. Если ваш API не справляется под нагрузкой, проблема в пропускной способности, а не в повторных попытках — и увеличение количества повторных попыток в этом случае только усугубляет ситуацию, поскольку умножает число вызовов. Сначала снизьте лимит.

Увеличение Maximum retries не заменяет стабильность API. Повторные попытки покрывают лишь кратковременную недоступность. Если ваш API отказывает часто, эта настройка лишь отсрочит момент, когда уведомление будет потеряно.

Шесть полей повторных попыток, отображаемые после включения переключателя.

Шаг 5 — Сохраните

Нажмите Save. Кнопка Cancel отменяет все изменения и сохраняет предыдущую конфигурацию.

Если выбран метод OAuth 2.0, IDCloud проверяет URL получения токена, прежде чем разрешить сохранение.

После сохранения карточка Your webhook показывает эндпоинт и тип аутентификации. Секрет отображается замаскированным, и получить его с экрана больше нельзя — если значение потеряно, нужно будет задать новое.

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

Часто задаваемые вопросы

Можно ли зарегистрировать больше одного вебхука? Нет. Действует правило — один вебхук на тенант и филиал. Если вебхук уже существует, он редактируется — создать второй невозможно.

Я настроил вебхук в Staging. Применяется ли это также к Production? Нет. Окружения независимы: портал Staging настраивает вебхук UAT, а портал Production — вебхук Production. Вам нужно повторить настройку в портале Production.

Как посмотреть зарегистрированный секрет? Это невозможно. Он шифруется при сохранении и всегда отображается замаскированным. Если значение потеряно, зарегистрируйте новое через поле Secret — при заполнении оно перезапишет предыдущее.

Я редактирую вебхук, но не хочу менять секрет. Что делать? Оставьте поле Secret пустым. Текущее значение будет сохранено.

Как удалить вебхук? На экране нет возможности удаления. Чтобы убрать конфигурацию, обратитесь в поддержку Unico. Если цель — просто прекратить получать уведомления или изменить адрес назначения, вместо удаления измените URL.

Я сохранил настройки, но уведомления не приходят. Проверьте по порядку: URL указан верно и использует HTTPS; ваш API доступен; метод аутентификации соответствует тому, что ожидает ваш API; секрет введён правильно. Ошибки аутентификации не отображаются на этом экране — они возникают на этапе доставки.

Чем отличаются «Maximum duration» и «Maximum time»? «Maximum time» — это наибольший интервал между двумя попытками. «Maximum duration» — это то, сколько IDCloud ждёт на каждую попытку, прежде чем считать её неудачной.

Нужен ли мне вебхук, если я уже получаю результат через опрос (polling) API? Это не обязательно, но вебхук избавляет вашу систему от необходимости опроса. Если у вас уже есть рабочая процедура опроса, вебхук — это оптимизация, а не обязательное требование.

Краткая справка

Портал IDCloud
 └─ Settings (значок шестерёнки в боковой панели)
     └─ Вкладка Webhook
         ├─ Client information ....... Client URL (Endpoint), HTTPS
         ├─ Authentication ............ None | API Key | Basic Auth | OAuth 2.0
         │                             OAuth 2.0: + Auth URL и Client ID
         └─ Retries (необязательно) ....... Maximum retries
                                       Rate limit (req/s)
                                       Minimum time (2s) · Maximum time (10s)
                                       Maximum duration (2s) · Maximum doublings (5)

Один вебхук на тенант и филиал · UAT и Production независимы · Secret никогда не отображается · Cancel · Save