# 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:**

```json
{
  "callbackApiKey": "callback-api-key-123",
  "type": "one-time-password-request",
  "sessionId": "wwb83rh1se22wd81z0tx8bqlerljq5kgf6rxem1q",
  "text": "Your code is 6867",
  "phoneNumber": "+995512345678"
}
```

### 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:**

```json
{
  "callbackApiKey": "apikey123",
  "type": "share-session-link-via-sms",
  "sessionId": "ku2a5ldv4i13go76ftkych1je055nvyjtvjuurkp",
  "text": "Hello John Doe, please complete your verification using the link below.",
  "phoneNumber": "+995512345678",
  "sessionLink": "https://widget.identomat.com/?session_token=ku2a5ldv4i13go76ftkych1je055nvyjtvjuurkp",
  "createdBy": "operator@example.com"
}
```

***

## 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:**

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

### 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:**

```json
{
    "callbackApiKey": "apikey123",
    "type": "email-one-time-password-request",
    "sessionId": "5alhw0070l2gy82q0mqlfniv7gwgbqqs0rtctolg",
    "address": "john.doe@example.com",
    "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.

### Callback Event: session-change

**Client must provide:**

* Callback URL
* Callback API key

**Sample callback payload:**

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

The `result` field in a `session-change` callback reflects the current session status. Possible values:

<table><thead><tr><th width="306.64453125">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>APPROVED</code></td><td>The session was approved.</td></tr><tr><td><code>REJECTED</code></td><td>The session was rejected.</td></tr><tr><td><code>MANUAL_CHECK</code></td><td>The session requires manual review.</td></tr><tr><td><code>ADDITIONAL_INFORMATION_REQUESTED</code></td><td>The operator has requested further verification from the applicant.</td></tr></tbody></table>

**KYB sessions**

For KYB sessions, the payload includes an additional `sessionType` field:

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

> If `sessionType` is 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"`), or
* the video file has been successfully **created and uploaded** (`videoFileStatus: "available"`).

**Client must provide:**

* Callback URL
* Callback API key

{% hint style="info" %}
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.**](/developer-tools/api-reference.md#result-session-results) 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`**](/developer-tools/api-reference.md#get-video-call-videos-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.
{% endhint %}

#### Case 1 — Room ended with no media recorded

**Sample callback payload:**

```json
{
  "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:**

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

<table><thead><tr><th width="236.953125">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>callbackApiKey</strong></td><td>Key used for authentication.</td></tr><tr><td><strong>type</strong></td><td>Always <code>"video-call-status-update"</code>.</td></tr><tr><td><strong>sessionId</strong></td><td>The ID of the verification session.</td></tr><tr><td><strong>roomId</strong></td><td>Unique identifier of the video room.</td></tr><tr><td><strong>roomStatus</strong></td><td>Indicates the state of the room (<code>empty</code>, <code>ended</code>).</td></tr><tr><td><strong>compositionStatus</strong></td><td>Status of composition file, if any (<code>available</code>, <code>null</code>).</td></tr><tr><td><strong>videoFileStatus</strong></td><td>Indicates whether the video file is ready (<code>available</code>, <code>null</code>).</td></tr><tr><td><strong>videoFileId</strong></td><td>Identifier of the uploaded video file, if available.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.identomat.com/developer-tools/callbacks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.