Callbacks

Learn how to receive and handle real-time status updates and event notifications from the verification flow using callbacks.

Overview

Callbacks allow your system to receive event notifications directly from the platform whenever specific actions occur, such as one-time password (OTP) creation, session sharing, or status updates.

Callbacks are sent as POST requests to the URL defined in your company settings. Each callback includes a callbackApiKey that can be used to verify authenticity.

Prerequisites

To enable callbacks, clients must configure the following parameters in their Company settings:

• Callback URL – endpoint where the callback payloads will be sent.

• Callback API key – a unique key for authentication and verification.

---

SMS provider callbacks

If the Client’s own SMS provider is selected in company settings, the system sends callback requests instead of delivering SMS directly. The client is then responsible for sending the SMS messages based on the received callback data.

Callback event: one-time-password

Description: Triggered when a one-time password (OTP) is generated and must be sent to the end-user during phone number verification.

Requirements:

• Callback URL (mandatory)

• Callback API key (mandatory)

Sample callback payload:

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

Callback event: share-session-link-via-sms

Description: Triggered when a session link is shared with a user via SMS from the Manage platform.

Requirements:

• Callback URL (mandatory)

• Callback API key (mandatory)

Sample callback payload:

{
  "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 provider callbacks

If your company uses Client's own provider in Email provider settings, Identomat will send callbacks to your system for sending emails.

Callback event: share-session-link-via-email

Description: Triggered when a verification session link is shared via email from the Manage platform.

Client must provide:

• Callback URL

• Callback API key

Sample callback payload:

{
  "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]"
}

Callback Event: email-one-time-password-request

Description: Triggered when a one-time password (OTP) is generated and must be sent to the end-user during email verification.

Requirements:

• Callback URL (mandatory)

• Callback API key (mandatory)

Sample callback payload:

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

---

Session status callbacks

This callback is independent of the provider settings. It notifies the client whenever a session’s status changes (e.g., APPROVED, REJECTED, MANUAL_CHECK).

Callback Event: session-change

Client must provide:

• Callback URL

• Callback API key

Sample callback payload:

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

---

Video call callbacks

These callbacks are triggered during the video call process and notify the client about the availability or absence of recorded video files.

The callback is sent regardless of whether a video was successfully created. This allows clients to detect when a room ended without media, or when a video file becomes ready for retrieval.

Callback event: video-call-status-update

Description: Sent whenever a video call room changes status. This includes cases where:

• the video call room ended with no media recorded (roomStatus: "empty"), or

• the video file has been successfully created and uploaded (videoFileStatus: "available").

Client must provide:

• Callback URL

• Callback API key

This callback is used for real-time notifications, but the complete and always up-to-date video call status is also available in the videoCallStatus field of the /result endpoint. This allows clients to poll /result or perform state recovery if any callback is missed. When a recording becomes available, we strongly recommend retrieving it using the fileId parameter of the /get-video-call-videos endpoint. Using fileId allows your system to download video files one-by-one, provides better control over large recordings, and avoids fetching unnecessary files.

Downloading all files in a single request is still supported for backward compatibility but is not recommended for new integrations.

Case 1 — Room ended with no media recorded

Sample callback payload:

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

Case 2 — Video file created and ready for retrieval

Sample callback payload:

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

Field	Description
callbackApiKey	Key used for authentication.
type	Always "video-call-status-update".
sessionId	The ID of the verification session.
roomId	Unique identifier of the video room.
roomStatus	Indicates the state of the room (empty, ended).
compositionStatus	Status of composition file, if any (available, null).
videoFileStatus	Indicates whether the video file is ready (available, null).
videoFileId	Identifier of the uploaded video file, if available.