Webhook

Markdown

Статьи о GetProcess в этой документации описывают способ получения статуса процесса с помощью вызова эндпоинта. Таким образом выполняется опрос (polling) для получения информации о созданных процессах. Это означает, что эндпоинт можно вызывать несколько раз для одного и того же процесса, чтобы получить самый актуальный статус.

С использованием Webhook можно уведомлять определённый эндпоинт каждый раз, когда статус процесса изменяется.

Что такое Webhook?

Webhook — это системный сервис уведомлений, который обеспечивает асинхронную интеграцию между системами, при которой одна система уведомляет другую с помощью триггера. Таким образом, Webhook позволяет поддерживать системы в актуальном состоянии, предоставляя самую свежую информацию без необходимости постоянного опроса для проверки обновлений.

Как настроить Webhook

Для настройки Webhook требуется следующая информация:

• URL уведомления: это эндпоинт, который Unico использует для отправки уведомлений об изменении статуса.
• Тип аутентификации: метод, используемый для аутентификации вызова эндпоинта. Доступны следующие варианты:
  • OAuth2;
  • Basic Authorization;
  • API Key;
  • Без аутентификации.
• Для OAuth2 необходимо предоставить следующую информацию:
  • Webhook endpoint;
  • URL провайдера OAuth2;
  • ClientId провайдера OAuth2;
  • Secret провайдера OAuth2.
• Для Basic Authorization необходимо передавать данные в формате user:pass.
• Для API Key возможны два формата:
  • header:value, если требуется конкретное имя заголовка;
  • value, если нужным заголовком является Authorization.
• Настройки повторных попыток: указывают количество попыток в случае сбоя при вызове эндпоинта:
  • Максимальное количество попыток;
  • Интервал между попытками (в секундах);
  • Rate Limit: максимальное количество одновременных отправок (макс.: 500);
  • Timeout: максимальное время ожидания ответа от эндпоинта (в секундах).
• Статусы для уведомления: вы можете подписаться на определённые статусы, чтобы получать уведомления. Среди них:
  • approved: транзакция одобрена;
  • processing: транзакция в обработке;
  • inconclusive: не удалось выполнить окончательную проверку;
  • shared: транзакция передана, ожидает отправки;
  • skipped: пользователь пропустил биометрический захват в потоке;
  • unknown-share: пользователь отметил, что не узнаёт покупку;
  • absent-holder: держатель карты отсутствует для выполнения захвата;
  • expired: пользователь не завершил захват в установленное время, и срок действия транзакции истёк.

Об аутентификации

API может быть защищён методом аутентификации, таким как Basic Authentication или API Key. Для дополнительной защиты также можно определить список разрешённых IP-адресов для доступа.

Интеграция с Верификацией без предъявления карты

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

Информация, отправляемая платформой в API, включает:

• ID: идентификатор транзакции;
• Status: статус транзакции;
• HasIdentityChanged: указывает, произошла ли смена личности в транзакции (необязательно).

примечание

Обратите внимание, что можно выбрать статусы, о которых клиент хочет получать уведомления, через настройку Webhook. После отправки этой информации ожидаемый ответ должен быть синхронным.

Запросы

Запрос должен выполняться методом POST к REST API, что упрощает и повышает безопасность отправки информации. Все поля должны быть обязательными. Тело запроса должно содержать идентификатор и статус транзакции, как показано в следующем примере:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

Ответ

Ответ должен быть синхронным. Статус успешных запросов должен находиться в диапазоне от 200 до 299. Любой другой статус будет считаться сбоем, и Верификация без предъявления карты будет предпринимать дополнительные попытки уведомления (с экспоненциальной задержкой между ними) до получения ответа 2xx или достижения максимального количества попыток.

Статус ответа

В настоящее время у нас есть определённый набор статусов, но в будущем он может измениться. Поэтому рекомендуется сделать настраиваемыми статусы, которые интересуют клиента для выполнения действий. Например, если целью является выполнение действия каждый раз при успешном завершении захвата, в настоящее время это происходит при статусе «processing». Однако, поскольку в будущем это может быть изменено, рекомендуется сделать статус, указывающий на успешный захват, настраиваемым в системе, чтобы будущее изменение на статус «captured» можно было легко внедрить.

Кроме того, мы рекомендуем предусмотреть отдельные действия для конкретных статусов и общее действие на случай нераспознанного статуса (например, считая неокончательным (inconclusive) всё, что отличается от «processing» и «approved»). Это важно, поскольку в будущем могут появиться новые статусы, и Webhook не должен из-за этого ломаться.

Важные аспекты

Обратите внимание на следующие аспекты при разработке API, который Верификация без предъявления карты будет использовать для уведомления об изменениях статуса:

Rate limit — чтобы избежать перегрузки ваших ресурсов при большом количестве транзакций, можно задать верхний предел количества вызовов эндпоинта.

Error Rate — доля ошибок (ответы вне диапазона [200, 299]) всегда должна оставаться низкой. В противном случае пропускная способность Webhook будет автоматически снижена, а это снижение в сочетании с механизмом повторных попыток может привести к увеличению времени выполнения новых Webhook-уведомлений.

Idempotence — текущая реализация Webhook гарантирует доставку не менее одного раза (at-least-once), поэтому один и тот же статус может быть отправлен более одного раза. Поэтому реализация эндпоинта должна быть идемпотентной.

Fallback — в случае недоступности сервиса Webhook рекомендуется иметь резервный (fallback) метод, чтобы продолжать получать статусы транзакций в установленное время ответа. Запрос к эндпоинту описан в разделе Справочник API этой документации.