---
title: Вебхук
description: Настройте, куда IDCloud отправляет уведомления вашей системе при изменении состояния процесса, как выполняется аутентификация при обращении к вашему API и что происходит, если ваш API не отвечает.
canonical: https://developer.unico.io/ru/dual-api/product-guide/portal-idcloud/settings/webhook
locale: ru
generated_by: markdown-export
---

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

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

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

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

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

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

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

Вашему пользователю нужен профиль **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**
для его редактирования.

![Карточка управления вебхуком с кнопкой Configure webhook](/img/product-guide/webhook/en/01-manage-webhook.png)

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

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

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

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

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

![Поле Endpoint с подсказкой о требовании HTTPS](/img/product-guide/webhook/en/02-edit-webhook.png)

*Поле 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 и соответствующие поля учётных данных](/img/product-guide/webhook/en/02-edit-webhook.png)

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

![Шесть полей повторных попыток, отображаемые после включения переключателя](/img/product-guide/webhook/en/02-edit-webhook.png)

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

### Шаг 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?** Это не
обязательно, но вебхук избавляет вашу систему от необходимости опроса. Если у вас уже есть рабочая
процедура опроса, вебхук — это оптимизация, а не обязательное требование.

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

```text
Портал 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
```