> For the complete documentation index, see [llms.txt](https://docs.preventor.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.preventor.com/server/webhooks/idv-tickets.md).
# IDV Tickets
Ticket webhook trigger
## 1. Event Types
Our webhook service supports two **events,** which describe the status of a *flow.* Those are:
* **ticket.verification.in\_progress**: your flow has completed a number of steps (subprocesses) and is waiting for user's intervention to continue to next steps or to retry previous failed one.
* **ticket.verification.completed**: your flow has completed its processing. It has been either `ACCEPTED` or `REJECTED`.
## **1.1 Verification - In Progress event**
The *ticket.verification.in\_progress* event is triggered when a *Verification* has completed a number of steps (subprocesses) and it's waiting for user-intervention to continue if it's appropriate. Notification payload specifies a set of properties as shown on following JSON. It will contain its ticket, so it can be tracked by your processes. Also, it holds its **event**, and its **sub\_event,** which will be explained later. The property **flow\_status** determines ticket's current state. The value of the **disposition** property can either be `PASSED` , `FAILED` or `RETRY`, which determines last executed subprocess' state. It also specifies how many attempts can be done on property **remaining\_attempts** if **disposition** has been set as `RETRY`. Property **data** contains suprocesses results, which we'll take a look afterwards.
```json
{
"ticket": "762ebbda-0edb-4e48-86bc-11a280273601",
"event": "ticket.verification.in_progress",
"sub_event": "verification.liveness",
"flow_status": "IN_PROGRESS",
"disposition": "PASSED",
"remaining_attempts": 3,
"data": { ... }
}
```
#### In Progress Event disposition statuses
* `PASSED:` all subprocesses were executed correctly and their results have been considered as OK.
* `RETRY`: this status is set when an exception has been raised, or any subprocess' result has been considered as unacceptable and has retries to attempt, ***eg.*** ***liveness detection*** process.
* `FAILED`, this status is set when an exception has been raised, or any subprocess' result has been considered as unacceptable and no more retries can be atempted, ***eg.*** ***liveness detection*** process.
#### Subevents
In this property, we will receive one of both values: `verification.liveness` and `verification.id_proofing`
#### verification.liveness subevent
This subevent is triggered when biometrical subprocesses were executed, which consist of `Facial analysis` and `Liveness detection`. In this subevent, property **data** contains biometrical subprocesses' results. An example is shown bellow:
```json
{
"ticket": "762ebbda-0edb-4e48-86bc-11a280273601",
"event": "ticket.verification.in_progress",
"sub_event": "verification.liveness",
"flow_status": "IN_PROGRESS",
"disposition": "PASSED",
"remaining_attempts": 3,
"data": {
"facial_analysis": {
"status": true,
"confidence_score": "100",
"age_range": "22-30"
},
"liveness_detection": {
"status": true,
"validation_messages": [
"Liveness detected"
]
}
}
}
```
#### verification.id\_proofing subevent
This subevent is triggered when Identity verification subprocesses were executed, which consist of `Document detection`, `Id proofing` and `Photo matching`. In this subevent, property **data** contains identity verification subprocesses' results. An example is shown bellow:
```json
{
"ticket": "762ebbda-0edb-4e48-86bc-11a280273601",
"event": "ticket.verification.in_progress",
"sub_event": "verification.id_proofing",
"flow_status": "IN_PROGRESS",
"disposition": "PASSED",
"remaining_attempts": 3,
"data": {
"document_detection": {
"status": true
},
"id_proofing": {
"status": true,
"validations": {
"recognized_document_type": "VALID",
"image_quality": "VALID",
"document_expiry": "VALID",
"mrz": "VALID",
"rfid": "NON_VALIDATED_OR_ABSENT",
"readability": "VALID",
"security": "VALID",
"general_status": "VALID",
"barcode": "VALID",
"authenticity": "NON_VALIDATED_OR_ABSENT",
"minimum_required_fields_read": "VALID"
}
},
"photo_matching": {
"status": true,
"similarity_score": "99.94"
}
}
}
```
## 1.2 Verification - Completed event
The *ticket.verification.completed* event is triggered when a *Verification* has completed all of its subprocesses, or an error has been raised and there are no more retries to attempt. Notification payload specifies a set of properties as shown on following JSON. It will contain its ticket, so it can be tracked by your processes. Also, it holds its **event**. The **flow\_status** specified ticket's current state, which can be either `ACCEPTED` or `REJECTED` , this value depends on **confidence\_score** property. The value of the **disposition** property can be either `PASSED` or `FAILED` which determines last executed subprocess' state. It also gives final results of entire flow, such as **risk\_code** and **confidence\_score**.
```json
{
"ticket": "72b89940-607f-4841-8521-5e641211917e",
"clientId": "CLIENT-ID",
"invitation": "a9e70162-97ae-4be0-8c53-caaaf6e99ba1",
"event": "ticket.verification.completed",
"flow_status": "ACCEPTED",
"disposition": "PASSED",
"risk_code": "LOW",
"confidence_score": 98.15,
"remaining_attempts": 0
}
```
#### Completed Event flow\_status statuses
* `ACCEPTED`: all flow's subprocesses were executed correctly and **confidence\_score** has got to *`ACCEPTED`* scoring threshold.
* `REJECTED`: this status is set when an exception has been raised, or any subprocess' result has been considered as unacceptable and no more retries can be atempted and **confidence\_score** has got to *`REJECTED`* scoring threshold.
#### Completed Event disposition statuses
* `PASSED:` all flow's subprocesses were executed correctly and their results have been considered as OK, so ticket is set to COMPLETED state.
* `FAILED`, this status is set when an exception has been raised, or any subprocess' result has been considered as unacceptable and no more retries can be atempted, ***eg.*** ***liveness detection*** process.
Here you find a further description of the response values below, it represents **both event responses** as these share the same response structure:
| Key | Data type | Description |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket` | `string` | The UUID of the *Identity Verification* which triggered this webhook. This will help you query our backend API for the details of the *Identity Verification*. |
| `invitation` | `string` | The UUID of the *Identity Verification* *Invitation* related to this ticket. |
| `event` | `string` | The type of event that triggered this webhook. |
| `flow_status` | `string` |
This holds the result of the processed ticket and its confidence\_score threshold matching.
As noted above, its value may be one of these 2 posibilities: - ACCEPTED - REJECTED
|
| `disposition` | `string` |
This holds the result of the last executed subprocess.
As noted above, its value may be one of these 2 posibilities: - PASSED - FAILED
|
| `remaining_attempts` | `number` | Specifies the number of remaining retries that could be attempted. |
| `risk_code` | `string` |
This contains risk analysis based on 3 possible values listed below, in order from safest to riskiest evaluation result: - LOW - MODERATE - HIGH
This value depends on confidence\_score result
|
| `confidence_score` | `number` | This value is the calculation result from all factors and subprocesses, going from 0 to 100. Used for ticket's **acceptance** or **rejection**. |