--- updatedAt: 2026-10-14T09:18:55.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. ### Note - All message types are prefixed with `idCheck`. - You can use the Test WebSDK tab inside a level to view WebSDK messages in real time, before going live. # `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" } ``` *** ### Note `onUploadError` is returned when Sumsub automatic checks reject a document right after upload. This applies to identity documents, proof of address, and company documents, both for file upload and for camera capture. code is the first rejection reason, and msg is the text shown to the applicant in the SDK language. The event does not trigger for network or server errors during upload, or applicant action flows. # `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" } ``` ### Note `idDocType`, `idDocSubType`, and `country` report the document Sumsub recognised from the uploaded image, not the values the applicant selected before uploading. If Sumsub does not return a recognised value, the field falls back to the selected one. For example, if the applicant selects a passport but uploads an image recognised as a driving licence, the event carries the driving licence. The event triggers for every stored image, including one that Sumsub rejects during upload. In that case `onUploadError` follows. # `onImageRemoved` A document image is removed. ```json { "imageId": 123456 } ```