Колбеки

Дізнайтеся, як отримувати та обробляти оновлення статусу в реальному часі та сповіщення про події з потоку верифікації за допомогою колбеків.

Огляд

Колбеки дозволяють вашій системі отримувати сповіщення про події безпосередньо з платформи щоразу, коли відбуваються певні дії, такі як створення одноразового пароля (OTP), поширення сесії чи оновлення статусу.

Колбеки надсилаються як POST-запити на URL, визначений у ваших налаштуваннях компанії. Кожен колбек включає callbackApiKey, який можна використати для перевірки автентичності.

Передумови

Щоб увімкнути колбеки, клієнти мають налаштувати такі параметри у своїх налаштуваннях компанії:

• Callback URL – ендпоінт, на який надсилатимуться дані колбеків.

• Callback API key – унікальний ключ для автентифікації та перевірки.

---

Колбеки провайдера SMS

Якщо в налаштуваннях компанії обрано власного SMS-провайдера клієнта, система надсилає запити колбеків замість прямої доставки SMS. Клієнт тоді відповідає за надсилання SMS-повідомлень на основі отриманих даних колбека.

Подія колбека: one-time-password

Опис: Спрацьовує, коли одноразовий пароль (OTP) генерується та має бути надісланий кінцевому користувачу під час верифікації номера телефону.

Вимоги:

• Callback URL (обов'язково)

• Callback API key (обов'язково)

Приклад даних колбека:

{
  "callbackApiKey": "callback-api-key-123",
  "type": "one-time-password-request",
  "sessionId": "wwb83rh1se22wd81z0tx8bqlerljq5kgf6rxem1q",
  "text": "Your code is 6867",
  "phoneNumber": "[phone]"
}

Подія колбека: share-session-link-via-sms

Опис: Спрацьовує, коли посилання на сесію надсилається користувачу через SMS із платформи Manage.

Вимоги:

• Callback URL (обов'язково)

• Callback API key (обов'язково)

Приклад даних колбека:

{
  "callbackApiKey": "apikey123",
  "type": "share-session-link-via-sms",
  "sessionId": "ku2a5ldv4i13go76ftkych1je055nvyjtvjuurkp",
  "text": "Hello John Doe, please complete your verification using the link below.",
  "phoneNumber": "[phone]",
  "sessionLink": "https://widget.identomat.com/?session_token=ku2a5ldv4i13go76ftkych1je055nvyjtvjuurkp",
  "createdBy": "[email protected]"
}

---

Колбеки провайдера email

Якщо ваша компанія використовує власного провайдера клієнта в налаштуваннях провайдера email, Identomat надсилатиме колбеки до вашої системи для надсилання листів.

Подія колбека: share-session-link-via-email

Опис: Спрацьовує, коли посилання на сесію верифікації поширюється через email із платформи Manage.

Клієнт має надати:

• Callback URL

• Callback API key

Приклад даних колбека:

{
  "callbackApiKey": "apikey123",
  "type": "share-session-link-via-email",
  "sessionId": "5alhw0070l2gy82q0mqlfniv7gwgbqqs0rtctolg",
  "address": "[email protected]",
  "subject": "Verification Required",
  "content": "Dear John Doe, please complete your verification using the link below.",
  "cc": "[email protected]",
  "sessionLink": "https://widget.identomat.com/?session_token=5alhw0070l2gy82q0mqlfniv7gwgbqqs0rtctolg",
  "createdBy": "[email protected]"
}

Подія колбека: email-one-time-password-request

Опис: Спрацьовує, коли одноразовий пароль (OTP) генерується та має бути надісланий кінцевому користувачу під час верифікації email.

Вимоги:

• Callback URL (обов'язково)

• Callback API key (обов'язково)

Приклад даних колбека:

{
    "callbackApiKey": "apikey123",
    "type": "email-one-time-password-request",
    "sessionId": "5alhw0070l2gy82q0mqlfniv7gwgbqqs0rtctolg",
    "address": "[email protected]",
    "subject": "Mail Verification",
    "content": "Your code is 6867"
}

---

Колбеки статусу сесії

Цей колбек не залежить від налаштувань провайдера. Він сповіщає клієнта щоразу, коли змінюється статус сесії.

Подія колбека: session-change

Клієнт має надати:

• Callback URL

• Callback API key

Приклад даних колбека:

{
  "callbackApiKey": "apikey123",
  "type": "session-change",
  "sessionId": "ku2a5ldv4i13go76ftkych1je055nvyjtvjuurkp",
  "result": "APPROVED"
}

Поле result у колбеку session-change відображає поточний статус сесії. Можливі значення:

Значення	Опис
APPROVED	Сесію затверджено.
REJECTED	Сесію відхилено.
MANUAL_CHECK	Сесія потребує ручного перегляду.
ADDITIONAL_INFORMATION_REQUESTED	Оператор запросив подальшу верифікацію у заявника.

Сесії KYB

Для сесій KYB дані включають додаткове поле sessionType:

{
  "callbackApiKey": "apikey123",
  "type": "session-change",
  "sessionId": "65lfvkv1t2o25ozimqu3nh797umb1ydvkpltl3ib",
  "result": "APPROVED",
  "sessionType": "kyb"
}

Якщо sessionType відсутнє, сесія є стандартною сесією KYC.

---

Колбеки відеодзвінка

Ці колбеки спрацьовують під час процесу відеодзвінка та сповіщають клієнта про доступність чи відсутність записаних відеофайлів.

Колбек надсилається незалежно від того, чи було успішно створено відео. Це дозволяє клієнтам виявляти, коли кімната завершилась без медіа, або коли відеофайл стає готовим для отримання.

Подія колбека: video-call-status-update

Опис: Надсилається щоразу, коли кімната відеодзвінка змінює статус. Це включає випадки, коли:

• кімната відеодзвінка завершилась без запису медіа (roomStatus: "empty"), або

• відеофайл було успішно створено та завантажено (videoFileStatus: "available").

Клієнт має надати:

• Callback URL

• Callback API key

Цей колбек використовується для сповіщень у реальному часі, але повний та завжди актуальний статус відеодзвінка також доступний у полі videoCallStatus ендпоінту /result. Це дозволяє клієнтам опитувати /result або відновлювати стан, якщо якийсь колбек було пропущено. Коли запис стає доступним, ми наполегливо рекомендуємо отримувати його за допомогою параметра fileId ендпоінту /get-video-call-videos. Використання fileId дозволяє вашій системі завантажувати відеофайли по одному, забезпечує кращий контроль над великими записами та уникає завантаження непотрібних файлів.

Завантаження всіх файлів в одному запиті все ще підтримується для зворотної сумісності, але не рекомендується для нових інтеграцій.

Випадок 1 — Кімната завершилась без запису медіа

Приклад даних колбека:

{
  "callbackApiKey": "apikey123",
  "type": "video-call-status-update",
  "sessionId": "wtmfcr7tcj4q04co8mdg8yryou9glrcr2tbzm016",
  "roomId": "RM860d0a0272a619cdc0b4a855e75f8466",
  "roomStatus": "empty",
  "compositionStatus": null,
  "videoFileStatus": null,
  "videoFileId": null
}

Випадок 2 — Відеофайл створено та готовий для отримання

Приклад даних колбека:

{
  "callbackApiKey": "apikey123",
  "type": "video-call-status-update",
  "sessionId": "ypsgyus3mosob3tugu3emgekqjykam5nvue1z1fu",
  "roomId": "RMc7eb8093d2461af50834f69e86692db3",
  "roomStatus": "ended",
  "compositionStatus": "available",
  "videoFileStatus": "available",
  "videoFileId": "hwenFYGlG54kRjmSruy3kxg54zV2pNPwHimseYao"
}

Поле	Опис
callbackApiKey	Ключ, що використовується для автентифікації.
type	Завжди "video-call-status-update".
sessionId	ID сесії верифікації.
roomId	Унікальний ідентифікатор кімнати відео.
roomStatus	Вказує статус кімнати (empty, ended).
compositionStatus	Статус файлу композиції, якщо є (available, null).
videoFileStatus	Вказує, чи готовий відеофайл (available, null).
videoFileId	Ідентифікатор завантаженого відеофайлу, якщо доступний.