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:
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:
Email provider callbacks
If your company uses Client's own provider in the 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:
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:
Session status callbacks
This callback is independent of the provider settings. It notifies the client whenever a session’s status changes.
Callback Event: session-change
Client must provide:
Callback URL
Callback API key
Sample callback payload:
The result field in a session-change callback reflects the current session status. Possible values:
APPROVED
The session was approved.
REJECTED
The session was rejected.
MANUAL_CHECK
The session requires manual review.
ADDITIONAL_INFORMATION_REQUESTED
The operator has requested further verification from the applicant.
KYB sessions
For KYB sessions, the payload includes an additional sessionType field:
If
sessionTypeis absent, the session is a standard KYC session.
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"), orthe 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:
Case 2 — Video file created and ready for retrieval
Sample callback payload:
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.
Last updated
Was this helpful?