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:

/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

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.