# Webhooks

**Overview**

This guide provides information on how to set up and verify VOVE ID's webhooks. Webhooks are essential for real-time notifications and integrations, enabling seamless communication between VOVE ID and your applications.

#### Receiving a Webhook

When an event occurs, our system will send a POST request to your specified webhook URL. Below is an example of the webhook request:

```http
/webhook-endpoint
Host: yourdomain.com
Accept: */*
Content-Length: 71
Content-Type: application/json
Svix-Id: msg_2if9qqkVjQDrS738JZOnax9T7MO
Svix-Signature: v1,k0P5dGMNLADVGNTBiMynIM8DgzNrpWvL/W28ikd/LDQ=
Svix-Timestamp: 1719870957
User-Agent: Svix-Webhooks/1.24.0

{
  "status": "successful",
  "refId": "2e96ebd0-c1b8-11ee-b56a-a345411e245d",
  "userId": "2e96ebd0-c1b8-11ee-b56a-a345411e245d" // ⚠️ Deprecated
}
```

> ⚠️ **Deprecated**: userId is retained for backward compatibility but will be removed in a future version. Use refId instead to identify users.

#### Status enum

| Value         | Meaning / typical next step                                                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `in_progress` | Verification started, and at least one step finished.                                                                                                                         |
| `pending`     | Awaiting manual review (if applicable).                                                                                                                                       |
| `successful`  | All checks passed, onboard the user.                                                                                                                                          |
| `suspected`   | Verification failed, for now the only failure reasons are either: Data Matching ("DOCUMENT\_INFO\_MISMATCHED") if applicable or AML check failed ("AML\_CHECK") if applicable |

#### Validating the Webhook

To ensure the webhook is legitimate, follow these steps:

1. **Extract the `Signature` from the header.**
2. **Generate the signature using the provided secret and compare it with the received signature.**

**Example in Node.js**

```javascript

const CryptoJS = require('crypto-js');

const webhookId = headers['Svix-Id'];
const webhookTimestamp = headers['Svix-Timestamp'];
const body = JSON.stringify({
  status: 'successful',
  userId: '2e96ebd0-c1b8-11ee-b56a-a345411e245d',
});
const signedContent = `${webhookId}.${webhookTimestamp}.${body}`;

// Use the secret you will get when you setup the webhook from dashboard
const secret = 'whsec_5WbX5kEWLlfzsGNjH64Ide8lOOqUB6e8FH';
const secretKey = secret.split('_')[1];

// Create the HMAC SHA-256 signature
const signature = CryptoJS.HmacSHA256(
  signedContent,
  CryptoJS.enc.Base64.parse(secretKey),
).toString(CryptoJS.enc.Base64);

const receivedSignature = headers['Svix-Signature'];
// Check if the signatures match.
if (signature === receivedSignature.split(',')[1]) {
  console.log('Webhook signature is valid.');
} else {
  console.log('Invalid webhook signature.');
}

```

#### Responding to Webhooks

* **200 OK**: Indicate successful processing.
* **4XX**: Client errors such as validation issues.

#### Retry Mechanism

Our system will retry the webhook delivery in case of failures with exponential backoff.

#### Testing Webhooks

Use tools like `ngrok` to expose your local server to the internet and simulate webhook requests for testing.

#### Checking Available Webhooks

To see the list of available webhooks, please visit the Webhooks section in the VOVE ID dashboard. Here, you will find detailed information about each webhook, including their events, payloads, and setup instructions. For more details, refer to the Webhooks section in the dashboard.

#### Obtaining the Webhook Secret

When you set the webhook URL in the VOVE ID dashboard, a unique secret key will be generated for your webhook. This secret is crucial for validating the webhook requests and ensuring their authenticity. You can find this secret in the Webhooks section of the dashboard after configuring your webhook URL.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voveid.com/docs/api/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.