--- title: "Event webhook | Veriff.com" slug: "event-webhook" description: "Configure Veriff's optional event webhook to track session status changes in identity verification. Learn about setup and event notifications in our guide." updated: 2025-07-23T08:34:15Z published: 2025-07-23T08:34:15Z --- > ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Event webhook This webhook is **optional** and should be configured if you are interested in getting**info about the progress of the verification data gathering**. If you decide to configure the webhook, you need to set `Webhook events URL` up in the Veriff Customer Portal. →*See Webhooks Guide > [Set up webhooks](https://veriff-dev-documentation.document360.io/docs/webhooks-guide#set-up-webhooks) sub-section for detailed overview of the setup process* --- ## When is event webhook sent? Veriff uses the event webhook to pass data about the verification session status change from “started” to “submitted”. The payload is sent to `Webhook events URL` and it tracks the events happening in the identity verification process performed by the end-user. **It does not provide info about the decision of the verification**. --- ## Prerequisites 1. Make sure you **have access to the Veriff Customer Portal** 1. If you do not, see the Getting Started → [Sign up](https://devdocs.veriff.com/docs/signing-up) and [Log in](https://devdocs.veriff.com/docs/logging-in) articles 2. Set up webhook URL(s) **on your side**and have them at hand 1. Make sure they **match** the [Webhook URL](https://devdocs.veriff.com/docs/webhooks-guide#webhook-url-requirements) requirements 2. Make sure your system is **able to handle** [Webhooks receipt, delivery and resending](https://devdocs.veriff.com/docs/webhooks-guide#webhook-delivery-receipt-and-resending) requirements 3. Check the [Webhooks headers and payload](https://devdocs.veriff.com/docs/webhooks-guide#webhooks-headers-and-payload) section for info 3. Secure your communication, check the [HMAC Authentication and Endpoint Security](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security) article 4. Make sure your system is **able to handle** the [Backwards compatible changes](https://devdocs.veriff.com/docs/backwards-compatible-changes) 5.Proceed to [Decision webhook setup section below](/v1/docs/decision-webhook#decision-webhook-setup) --- ## Events webhook set up 1. Log in to the **Veriff Customer Portal** 2. Navigate to the **Integrations** page via the top menu and open the relevant integration 3. On the integration's page, select the **Settings** tab 4. Under the title **Integration settings** you see a list of webhooks 5. Fill in the `Webhook events URL` →*See Webhooks Guide > [Set up webhooks](https://veriff-dev-documentation.document360.io/docs/webhooks-guide#set-up-webhooks) sub-section for detailed overview of the setup process* --- ## Sample request ```json {  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",  "feature": "selfid",  "code": 7002,  "action": "submitted",  "vendorData": "12345678",  "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4" } ``` ## Request properties explained - `id`: `string`* UUID v4 which identifies the verification session - `attemptId`: `string`* UUID v4 which identifies session attempt - `feature`: `string`* Feature on which the event was triggered (`selfid` refers to the end-user flow) - `code`: `integer`* Event code, one of `7001`, `7002` - `action`: `string`* Name of the triggered event, one of `started`, `submitted`, `waiting_continued`, `waiting_complete`, `flow_finished`, `flow_cancelled`, `document_type_other_selected` - `vendorData`: `string | null`* The unique identifier that you created for your end-user. `null` if not specified - `endUserId`: `string | null`* The unique UUID that you created for your end-user. `null` if not specified - `context`: `object` Object containing info about possible reasons why the event was triggered. Optional, present only if the [additional end-user flow events](/v1/docs/event-webhook#additional-enduser-flow-events) tracking is enabled for the integration - `reason`: `string` Indicates the reason why the event was triggered - `state`: `string` Indicates the state of the end-user flow at the moment of flow stopping, i.e. when the event was triggered (e.g., because the flow was finished or abandoned) *Required field --- ## Possible events over the webhook > [!NOTE] > 7007-7010 events can be received only when you are using Veriff's web flow, and these require some additional configuration on Veriff side. > > Contact your **solutions engineer** for info and configuration. | Webhook code | `action` value aka event name aka webhook action | Description | Available | Configuration to receive events | "Waiting for decision" page enabled | | --- | --- | --- | --- | --- | --- | | 7001 | started | The end-user arrives to Veriff verification flow and **starts** the verification process | via API and SDK/Web | Not needed | Not needed | | 7002 | submitted | The end-user is done with the process and **submits** the attempt. This webhook is sent before the end-user is directed to the callback URL specified on session creation (if applicable). | via API and SDK/Web | Not needed | Not needed | | 7007 | waiting_complete | The end-user **gets the decision** on the "waiting for decision" page | Web only | Yes, required | Yes, required | | 7008 | waiting_continued | The end-user **clicks on the Continue** button on the "waiting for decision" page **before the decision is available**. This triggers the action that you have configured for the case when the end-user finishes the flow. | Web only | Yes, required | Yes, required | | 7009 | flow_finished | The end-user reached the final screen and **clicked** on the**Continue** button | Web only | Yes, required | Not needed | | 7010 | flow_cancelled | The end-user **abandons the verification** flow | Web only | Yes, required | Not needed | | 7011 | document_type_other_selected | The end-user indicates that they want to use another document type for verification | Web only | Yes, required | Not needed | There are also events which Veriff does not notify you about. Log in to your Veriff account and see the [Verification statuses and decisions meaning](https://help.veriff.com/en/articles/3250231-meanings-of-various-verification-statuses-and-decisions)[↗]****article In Veriff Knowledge Base for more info. --- ## Additional end-user flow events If you are using Veriff’s web flow and the additional end-user flow events tracking has been enabled for your integration, events 7007-7010 may send additional info. The payload may include: - `action` string, naming the end-user flow event aka webhook action (see the table above) - a `context` object, containing the optional: - `reason` string, explaining why the event was triggered and giving some context to the `action` string - `state` string, indicating when the event was triggered by describing the state of the end-user flow at the moment of flow stopping (e.g., because the flow was finished or abandoned) > [!NOTE] > *→ See the*[*End-user flow events (table)*](/v1/docs/end-user-flow-events-table)*article for more detailed overview of possible*`reason`*and*`state`*values* #### Sample request when the end-user received the decision on the "waiting for decision" page ```json {  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",  "feature": "selfid",  "code": 7007,  "action": "waiting_complete",  "context": {      "reason": "final_decision_received"  },  "vendorData": "QWE123",  "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4" } ``` #### Sample request when the end-user finished the flow ```json {  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",  "feature": "selfid",  "code": 7009,  "action": "flow_finished",  "context": {      "reason": "finished_screen_confirmed_clicked",      "state": "finished_screen_shown"  },  "vendorData": "QWE123",  "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4" } ``` #### Sample request when the end-user abandoned the flow ```json {  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",  "feature": "selfid",  "code": 7010,  "action": "flow_cancelled",  "context": {      "reason": "quit_session_confirmed",      "state": "camera_access_blocked_screen_shown"  },  "vendorData": "QWE123",  "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4" } ``` --- ## Changelog | Date | Description | | --- | --- | | Jul 23, 2025 | Improvements to [Additional end-user flow events](/v1/docs/event-webhook#additional-enduser-flow-events) section | | Jun 6, 2025 | Heading “Article versioning” changed to “Changelog” | | May 7, 2025 | - Tables showing the possible values for `reason` and `state` strings in the event webhook payload have been moved to a separate new article: [End-user flow events (table)](/v1/docs/end-user-flow-events-table). The lists there have been updated with new values. - Updated the note about 7002 `submitted` webhook action | | Mar 12, 2025 | Documentation published | A session during which the end-user is verified. It starts when a session is created, it can contain several attempts (i.e. steps of uploading media, sending additional data etc.) and it ends when a conclusive decision (“approved”, “declined”, “expired”/”abandoned”) is granted. Each verification session receives an unique ID, aka the **session ID**, which can be added to the API URL when making API requests. Changes to the verification session status. **User of Veriff customer's solution**, the person who goes through the verification flow (aka "end-user flow"). This is returned after the end-user's data has been analysed and the system has reached a conclusion about the end-user's verification session. Can be `approved`, `declined`, `resubmission_requested`, `expired` or `abandoned`. Only if previously agreed with Veriff, you may also be receiving `review`. ## Related - [Webhooks Guide](/webhooks-guide.md)