> For the complete documentation index, see [llms.txt](https://docs.identomat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.identomat.com/developer-tools/webhooks.md).

# Webhooks

Receive real-time notifications on your server when a session is decided, a video call ends, or a code or link needs to be delivered.

## Overview

A webhook is an HTTPS endpoint on your server. Whenever an event it subscribes to happens, Identomat sends it a `POST` request with a JSON body. Your system doesn’t need to poll the API to find out whether a session has been decided.

Webhooks are managed in Manage under **Developers → Webhooks** and are available to Administrators. You can create as many as you need. Each one has its own callback URL, events and API key. For example, session decisions can go to your onboarding backend and video call updates to a separate archive service.

{% hint style="info" %}
**Coming from callbacks?**&#x20;

Webhooks replace the Callback URL and Callback API key fields that used to be in Company settings. Callbacks configured there were moved to Developers → Webhooks automatically. They keep the same URL and key and are named **Migrated webhook**. The payload format hasn’t changed. The SMS and email provider choice stays in Company settings → Communication providers.
{% endhint %}

### **Setting up a webhook**

1. **Prepare your endpoint.** It must be reachable over `https://` from the internet and accept `POST` requests with a JSON body. It must check that `callbackApiKey` matches your stored key and respond with a **2xx** status code within **20 seconds**.
2. **Create the webhook.** In Manage, go to **Developers → Webhooks** and click **+ New webhook**. Fill in:
   * **Callback URL**: your endpoint, starting with `https://`
   * **Events**: one or more of the events listed below. The **Payload preview** next to the form shows the exact JSON for each event you select.
3. **Copy the API key.** Click **Create webhook**. Identomat generates the webhook’s **Callback API key**. Copy it or download it as a `.txt` file and store it on your server.
4. **Test it.** Click **Continue**, then **Test webhook**. If the test passes, the webhook becomes **Active** and starts receiving events. If your endpoint isn’t ready yet, choose **Skip testing** and test later from the webhook list.

#### **Webhook statuses**

A webhook receives events only once it has passed a test.

<table><thead><tr><th width="116.68359375">Status</th><th width="449.7109375">Meaning</th><th>Receives events</th></tr></thead><tbody><tr><td>Not tested</td><td>Created, or its callback URL was changed, and not tested since</td><td>No</td></tr><tr><td>Failed</td><td>The last test didn’t pass</td><td>No</td></tr><tr><td>Active</td><td>Tested successfully</td><td>Yes</td></tr><tr><td>Deactivated</td><td>Switched off manually</td><td>No</td></tr></tbody></table>

{% hint style="warning" %}
Events that happen while a webhook isn’t **Active** are not queued or sent later. To catch up after downtime, call `result/` for the affected sessions.
{% endhint %}

Changing the **callback URL** of an Active webhook sets it back to Not tested until it passes a new test. Adding or removing **events** takes effect immediately and needs no new test.

#### **Testing a webhook**

A test sends one sample request for **each subscribed event** and shows how your endpoint answered: status code, response time and the request body. The test passes only if **every** request gets a 2xx response within 20 seconds.

Test requests carry your real API key and the header `X-Identomat-Test: true`. Use the header to skip test requests in your processing, so sample sessions aren’t treated as real.

<table><thead><tr><th width="192.69140625">Status before the test</th><th>Test passes</th><th>Test fails</th></tr></thead><tbody><tr><td>Not tested or Failed</td><td>Becomes Active</td><td>Becomes Failed</td></tr><tr><td>Active</td><td>Stays Active</td><td>Stays Active (the result is only shown)</td></tr><tr><td>Deactivated</td><td>Can’t be tested. Activate it first.</td><td>—</td></tr></tbody></table>

### **Verifying requests**

Every request includes the webhook’s key in the `callbackApiKey` field of the body. Compare it with the key you stored. Reject any request where it doesn’t match, for example with `401`.

* Each webhook has its own key, starting with `whsec_`.&#x20;
* You can view and copy the key at any time on the webhook’s detail page in Manage.
* **Generate new API key** replaces it. The old key stops working immediately, so update your endpoint first. Events sent while your endpoint rejects the new key are not resent.

### **Delivery**

* **Method:** `POST`, `Content-Type: application/json`, HTTPS only
* **Timeout:** 20 seconds. Any non-2xx response counts as a failed delivery.
* **Retries:** Failed deliveries are retried, so your endpoint may receive the same event more than once. Handle duplicates.
* **Delivery history:** Manage doesn’t show delivered events or let you resend them yet. Until it does, use `result/` to get a session’s current state, or contact Identomat support to resend events.

### **Identomat IP addresses**

Webhook requests are sent from these IP addresses:

* `63.179.37.212`
* `63.176.25.15`
* `34.159.23.239`

If your firewall limits incoming traffic, add all three to its allowlist so requests from Identomat reach your endpoint. Checking the IP doesn’t replace checking `callbackApiKey`. Always verify the key as well.

***

## **Events**

Events appear in Manage under their technical key, the same value your system receives in the `type` field.

<table><thead><tr><th>Event</th><th width="342.5390625">Sent when</th><th>Needs Client’s own provider</th></tr></thead><tbody><tr><td><code>session-change</code></td><td>A session’s result changes</td><td>No</td></tr><tr><td><code>video-call-status-update</code></td><td>A video call room or its recording changes status</td><td>No</td></tr><tr><td><code>one-time-password</code></td><td>An applicant needs an SMS one-time code (Phone number step, verify method)</td><td>Yes, SMS</td></tr><tr><td><code>share-session-link-via-sms</code></td><td>An operator shares a verification link by SMS from Manage</td><td>Yes, SMS</td></tr><tr><td><code>email-one-time-password-request</code></td><td>An applicant needs an email one-time code (Email step, verify method)</td><td>Yes, email</td></tr><tr><td><code>share-session-link-via-email</code></td><td>An operator shares a verification link by email from Manage</td><td>Yes, email</td></tr></tbody></table>

{% hint style="info" %}
The four code and link events are sent only when **Client’s own provider** is selected in Company settings → Communication providers. Your system then delivers the SMS or email itself. With Identomat as provider, Identomat sends the message and these events never fire. Choosing your own provider without an Active webhook for these events means codes and links reach no one.
{% endhint %}

### **session-change**

Notifies your system whenever a session’s status changes. This event doesn’t depend on the SMS or email provider settings.

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

<table><thead><tr><th width="302.21484375">result</th><th>Meaning</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 needs manual review</td></tr><tr><td><code>ADDITIONAL_INFORMATION_REQUESTED</code></td><td>An operator asked the applicant for further verification. See Additional information requests.</td></tr></tbody></table>

**KYB sessions** also include `"sessionType": "kyb"`. If `sessionType` is absent, the session is KYC. Get the full data from `result/` (KYC) or the KYB `result` endpoint.

### **video-call-status-update**

Sent whenever a video call room changes status. It is sent whether or not a video was recorded, so your system can tell when a room ended with no media and when a recording is ready to download.

**Case 1: room ended with no media recorded** (`roomStatus: "empty"`)

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

**Case 2: video file created and ready to download** (`videoFileStatus: "available"`)

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

<table><thead><tr><th width="193.2265625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>callbackApiKey</code></td><td>The webhook’s key, used to verify the request</td></tr><tr><td><code>type</code></td><td>Always <code>video-call-status-update</code></td></tr><tr><td><code>sessionId</code></td><td>ID of the verification session</td></tr><tr><td><code>roomId</code></td><td>Unique ID of the video room</td></tr><tr><td><code>roomStatus</code></td><td>State of the room: <code>ended</code>, or <code>empty</code> when the room ended with no media recorded</td></tr><tr><td><code>compositionStatus</code></td><td>Status of the composition file: <code>available</code> or <code>null</code></td></tr><tr><td><code>videoFileStatus</code></td><td>Whether the video file is ready: <code>available</code> or <code>null</code></td></tr><tr><td><code>videoFileId</code></td><td>ID of the uploaded video file, or <code>null</code>. Pass it as <code>fileId</code> to <code>get-video-call-videos</code>.</td></tr></tbody></table>

This event is a real-time notification. The complete, always up-to-date video call status is also in the `videoCallStatus` field of the `result/` endpoint, so your system can poll `result/` or recover the state if an event is missed.

{% hint style="info" %}
When a recording becomes available, we strongly recommend downloading it with the `fileId` parameter of `get-video-call-videos`. With `fileId`, your system downloads files one at a time, keeps better control over large recordings, and skips files it doesn’t need. Downloading all files in one request is still supported for backward compatibility, but isn’t recommended for new integrations.
{% endhint %}

### **one-time-password-request**

Sent when a one-time password is generated during phone number verification and must be delivered to the end-user by SMS.

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

Send `text` to `phoneNumber` as an SMS.

### **share-session-link-via-sms**

Sent when an operator shares a session link with the end-user by SMS from Manage.

```json
{
  "callbackApiKey": "whsec_...",
  "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-one-time-password-request**

Sent when a one-time password is generated during email verification and must be delivered to the end-user by email.

```json
{
  "callbackApiKey": "whsec_...",
  "type": "email-one-time-password-request",
  "sessionId": "5alhw0070l2gy82q0mqlfniv7gwgbqqs0rtctolg",
  "address": "john.doe@example.com",
  "subject": "Mail Verification",
  "content": "Your code is 6867"
}
```

### **share-session-link-via-email**

Sent when an operator shares a session link with the end-user by email from Manage.

```json
{
  "callbackApiKey": "whsec_...",
  "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"
}
```

***

#### **Best practices**

* **Respond first, process later.** Return 2xx as soon as the request arrives and do the work afterwards, because of the 20-second limit.
* **Treat `session-change` as a signal.** Call `result/` for the decision details before acting on it.
* **Handle repeats.** The same event can arrive more than once, for example when support resends it. Use `sessionId` + `type` + `result` to skip duplicates.
* **Use one webhook per environment**, such as “Staging – decisions” and “Production – decisions”, each with its own URL and key.
* **Deactivate rather than delete** during maintenance on your side. You keep the configuration and key.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.identomat.com/developer-tools/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
