---
updatedAt: 2026-09-23T09:16:19.000Z
agentTools:
  projectIndex: https://docs.sumsub.com/llms.txt
---

# WebSDK messages

Interpret event messages from Sumsub WebSDK.

After you configure an `on` handler function, the WebSDK sends event messages for key moments in the verification flow — status changes, applicant actions, and more. This page describes each message type and its payload.

<Callout icon="📘" theme="info">
  ### Note

  - All message types are prefixed with `idCheck`.
  - You can use the <Anchor target="_blank" href="doc:configure-verification-levels#test-websdk-verification-flow">Test WebSDK</Anchor> tab inside a level to view WebSDK messages in real time, before going live.
</Callout>

# `onReady`

WebSDK resources have been loaded. Empty payload.

***

# `onInitialized`

First screen is rendered. Empty payload.

***

# `onStepInitiated`

Screen that corresponds to `$idDocSetType` was shown.

```json
{
  "idDocSetType": "$idDocSetType",
  "types": ["$idDocType1", "$idDocType2"]
}
```

***

# `onLivenessCompleted`

Applicant completed a Liveness attempt (the applicant may pass several attempts depending on the settings).

> Applies to WebSDK 2.0 only.

```json
{
  "answer": "$answer",
  "allowContinuing": true | false
}
```

***

# `stepCompleted` / `onStepCompleted`

Step `$idDocSetType` has been completed.

> In WebSDK, the event is named `stepCompleted` or `onStepCompleted`. In WebSDK 2.0, it is named `onStepCompleted`.

In WebSDK:

```json
{
  "step": "$idDocSetType"
}
```

In WebSDK and WebSDK 2.0:

```json
{
  "idDocSetType": "$idDocSetType"
}
```

***

# `onVerificationProgressChanged`

The applicant verification progress has changed. This message reports the current verification step and the total number of verification steps, so you can render your own progress indicator outside the WebSDK. Sent whenever `currentStep` or `totalSteps` changes.

* `currentStep` — the current verification step, 1-based. Only verification steps are counted; service and helper screens are excluded. It is 0 on a service screen shown before verification starts.
* `totalSteps` — the total number of verification steps in the applicant level.
* On a re-take/resubmission screen, `currentStep` reflects the steps already approved plus the step being re-taken, so progress does not reset to zero for a returning applicant.

```json
{
  "currentStep": 2,
  "totalSteps": 5
}
```

***

# `onApplicantLoaded`

Applicant with ID `$id` has been loaded.

```json
{
  "applicantId": "$id"
}
```

***

# `onApplicantSubmitted`

Documents were submitted for verification. Empty payload.

***

# `onError`

Verification error occurred. The `reason` field is optional and supported only for the `camera-error` code.

```json
{
  "code": "invalid-origin" | "initialization-error" | "invalid-token" | "camera-error" | "invalid-config",
  "error": "Error message",
  "reason": "permissionsDenied"
}
```

***

# `applicantStatus` / `onApplicantStatusChanged`

Applicant status has been changed.

> In WebSDK, the event is named `applicantStatus`. In WebSDK 2.0, it is named `onApplicantStatusChanged`.

```json
{
  "reprocessing": false,
  "levelName": "$levelName",
  "createDate": "$createDate",
  "expireDate": "$expireDate",
  "reviewStatus": "$reviewStatus",
  "reviewResult": "$reviewResult",
  "autoChecked": false
}
```

***

# `onApplicantResubmitted`

Documents re-submitted for verification. Empty payload.

***

# `onApplicantActionLoaded`

Applicant action with ID `$id` has been loaded.

```json
{
  "applicantActionId": "$id"
}
```

***

# `onApplicantActionStatusChanged`

Applicant action status has been changed.

```json
{
  "reprocessing": true | false,
  "levelName": "$levelName",
  "creationDate": "$creationDate",
  "expireDate": "$expireDate",
  "reviewStatus": "$reviewStatus",
  "autoChecked": true | false
}
```

***

# `onApplicantActionSubmitted`

Applicant action was submitted. Empty payload.

***

# `onApplicantActionCompleted`

Applicant action `$id` was completed.

```json
{
  "action": "$actionType",
  "applicantActionId": "$id",
  "answer": "$answer"
}
```

***

# `moduleResultPresented`

Result of the standalone module has been presented to the user. Valid only for the `module` customization type. Happens either when the user has just completed the check or when the user reopened the module for a previously completed check.

Possible answers:

* **GREEN** — check was successful.
* **YELLOW** — user is allowed to proceed; final check result will be determined later.
* **RED** — user has been decisively rejected and is not allowed to proceed.

Not shown if the rejection is not final.

```json
{
  "answer": "GREEN"
}
```

***

# `onResize`

WebSDK frame has been resized.

```json
{
  "height": 159
}
```

***

# `onVideoIdentCallStarted`

Video call was started by the user. Empty payload.

***

# `onVideoIdentModeratorJoined`

Video call was answered by operator. Empty payload.

***

# `onVideoIdentCompleted`

Video call was completed by operator. Empty payload.

***

# `onUploadError`

Uploaded document was rejected.

```json
{
  "code": "$error",
  "msg": "Error message"
}
```

***

<Callout icon="📘" theme="info">
  ### Note

  `onUploadError` is returned when an uploaded document is rejected during an of the document upload steps (identity document, proof of address, company documents, or web-camera photo capture).
</Callout>

# `onUploadWarning`

Warnings about the uploaded document.

```json
{
  "code": "$warning",
  "msg": "Warning message"
}
```

***

# `onNavigationUiControlsStateChanged`

State of the navigation controls in the SDK. Pass `controlledNavigationBack: true` in the config to enable this event.

```json
{
  "previousScreenButton": "normal" | "disabled" | null,
  "closeModalButton": "normal" | null
}
```

***

# `onApplicantLevelChanged`

Applicant level has been changed.

Possible causes for the level change:

* Verification logic in [Workflow Builder](https://docs.sumsub.com/sumsub/docs/workflow-builder).
* Use of the [Manage level](https://docs.sumsub.com/sumsub/docs/change-verification-level) functionality.
* Reverting to the previous verification level via SDK.

```json
{
  "levelName": "newLevelName"
}
```

***

# `onApplicantVerificationCompleted`

Applicant verification is fully completed and a final review result is available.

> This message will not be shown if the applicant level changes as part of a workflow step.

```json
{
  "reprocessing": true | false,
  "levelName": "$levelName",
  "createDate": "$createDate",
  "reviewStatus": "$reviewStatus",
  "reviewResult": "$reviewResult",
  "autoChecked": false
}
```

# `onDocumentAdded`

An applicant successfully uploads a document image. `imageId` is always present; `idDocSetType`, `idDocType`, `idDocSubType`, and `country` are included when known.

```json
{
  "imageId": 123456,
  "idDocSetType": "$idDocSetType",
  "idDocType": "$idDocType",
  "idDocSubType": "$idDocSubType",
  "country": "$country"
}
```

<Callout icon="📘" theme="info">
  ### Note

  `idDocType`, `idDocSubType`, and `country` report the document Sumsub recognised from the uploaded image, not the values the applicant declared before uploading.&#x20;

  When a recognised value is not returned, the field falls back to the value the applicant declared.&#x20;
</Callout>

# `onImageRemoved`

A document image is removed.

```json
{
  "imageId": 123456
}
```