> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/identity-operation-center/conversion-ops/webhook-notification.md).

# Webhook Notification

The Webhook is a way for VIDA to notify partners about updates on identity verification transactions. When a webhook is configured, VIDA will send notifications to the partner's API containing the status of the verification process and other relevant information, such as the unique transactionId and the partner's own transaction ID partnerTrxId (if provided in the API request). This allows partners to easily track the status of their API requests. To receive webhook notifications, the partner's API should be able to accept JSON requests, and should be configured to accept the webhook URL, authentication method, and authentication credentials provided by VIDA. 

### Webhook Configuration

To set up Webhooks, you will need to contact the VIDA support team. and request for it to be enabled. Please reach out to the VIDA support team for further assistance.

### Authorization

VIDA supports OAuth2-based "client credentials" and "Basic Auth" methods for authentication. The partner must share their preferred method of authentication along with the necessary credentials and URL to receive the webhook notifications.

### Invocation Request

The invocation request from the webhook is identical to the response received from the Status check API.

### Invocation Request Status Code

The status check failure reasons table covers all the possible status code along with the description and recommendation in case of failure. 

### Webhook Payload Structure

The webhook payload structure will inform partners with the API processing status, for example when the request API is still in-progress due to manual review, or to notify if the transaction successfully processed. 

<details>

<summary>JSON Response</summary>

```json
{
  "data": {
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": "<code>"
  }
}
```

</details>

The ***status*** field provides detailed information about the current state of the fraud assessment transaction. It may contain the following values:

<table><thead><tr><th width="107.92193603515625">Status</th><th>Description</th></tr></thead><tbody><tr><td>001</td><td>The fraud assessment is in progress</td></tr><tr><td>002</td><td>The fraud assessment transaction is submitted for manual review</td></tr><tr><td>003</td><td>The fraud assessment result is accepted and the certificate issued after manual review</td></tr><tr><td>004</td><td>The fraud assessment result is rejected and the certificate have been not issued after manual review</td></tr><tr><td>006</td><td>The certificate not issued</td></tr><tr><td>007</td><td>Certificate is issued</td></tr></tbody></table>

### Example of Webhook Payload

{% tabs %}
{% tab title="When the API in Progress" %}

```json
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 001
}
```

{% endtab %}

{% tab title="Submitted for Post Correction" %}

```json
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 002
}
```

{% endtab %}

{% tab title="Post Correction Accepted" %}

```json
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 003
}
```

{% hint style="info" %}
**status**: The status of the fraud assessment (ACCEPTED).
{% endhint %}
{% endtab %}

{% tab title="Post Correction Rejected" %}

```json
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 004
}
```

{% hint style="info" %}
**status**: The status of the post-correction result if the verification is rejected (REJECTED).
{% endhint %}
{% endtab %}

{% tab title="Digital Certificate Issued" %}

```json
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 007
}
```

{% endtab %}

{% tab title="When the digital certificate is not issued" %}
This event the digital certificate is not issued, the payload is as follows:

```json5
{
    "partnerTrxId": "3282d003-c62c-4b7b-87e4_12112",
    "transactionType": "FULL_FRAUD_ASSESSMENT",
    "transactionId": "3282d003-c62c-4b7b-87e4-9d0a1bbf0c18",
    "status": 006
}
```

{% endtab %}
{% endtabs %}