VOVE ID uses webhooks to send real-time notifications about KYB case events to your application. Webhooks allow you to receive immediate updates when a case status changes, a UBO is invited, or verification is completed, eliminating the need for polling the API.
Webhooks are powered by Svix, providing reliable delivery, automatic retries, and webhook signature verification.
Setting Up Webhooks
Dashboard Configuration
Log in to the VOVE ID dashboard
Navigate to Settings → Webhooks
Add your webhook endpoint URL (must be HTTPS)
Select which event types you want to receive
Save and note your webhook signing secret
Endpoint Requirements
Your webhook endpoint must:
Accept HTTP POST requests
Use HTTPS (HTTP is not supported for production)
Return a 2xx status code within 15 seconds
Verify the webhook signature (recommended for security)
Webhook Events
KYB Case Events
kyb.case.created
Triggered when a new KYB case is created.
Payload:
kyb.case.status.changed
Triggered when a case status changes (e.g., NOT_STARTED → IN_PROGRESS → IN_REVIEW → COMPLETED/REJECTED).
Payload:
kyb.case.completed
Triggered when a case is approved and marked as completed.
Payload:
kyb.case.rejected
Triggered when a case is rejected.
Payload:
UBO Events
kyb.ubo.invited
Triggered when a UBO is invited to complete their verification.
Payload:
kyb.ubo.completed
Triggered when a UBO completes their KYC verification.
Payload:
Implementing Webhook Handlers
Node.js/Express Example
Python/Flask Example
Security Best Practices
Signature Verification
Always verify webhook signatures to ensure the request is from VOVE ID:
Get the svix-signature header from the request
Compute the expected signature using your webhook secret
Compare the signatures using a timing-safe comparison
Reject requests with invalid signatures
Idempotency
Webhooks may be delivered more than once. Implement idempotency handling:
For production systems, use a database instead of an in-memory Set.
Error Handling
Return appropriate status codes:
200-299: Success, webhook acknowledged
400-499: Client error, will not be retried
500-599: Server error, will be retried with exponential backoff
Timeout Handling
Respond quickly (within 15 seconds) to avoid timeouts:
Testing Webhooks
Local Development with ngrok
Use ngrok to expose your local server for webhook testing:
Testing with cURL
Simulate webhook events locally:
Webhook Retry Logic
VOVE ID automatically retries failed webhook deliveries:
Initial retry: After 5 seconds
Subsequent retries: Exponential backoff up to 1 hour
Maximum attempts: 5 attempts over 24 hours
Failure criteria: Non-2xx response or timeout
Failed webhooks are logged in the dashboard for manual review and retry.
Monitoring and Debugging
Dashboard Monitoring
Monitor webhook delivery in the VOVE ID dashboard:
View recent webhook deliveries
Check delivery status (success/failed)
View request/response details
Manually retry failed webhooks
Logging
Implement comprehensive logging in your webhook handler:
Common Use Cases
Update Case Status in Database
Enable Business Account on Completion
Notify Customer on Rejection
Track UBO Verification Progress
Related Documentation
KYB Overview - Understand the KYB verification flow
const express = require('express');
const crypto = require('crypto');
const app = express();
// Use raw body for signature verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString();
}
}));
// Webhook signing secret from VOVE ID dashboard
const WEBHOOK_SECRET = process.env.VOVE_WEBHOOK_SECRET;
// Verify webhook signature
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('base64');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Webhook endpoint
app.post('/webhooks/vove-kyb', (req, res) => {
// Get signature from header
const signature = req.headers['svix-signature'];
// Verify signature
if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
console.error('Invalid webhook signature');
return res.status(401).send('Invalid signature');
}
const event = req.body;
// Handle different event types
switch (event.type) {
case 'kyb.case.created':
handleCaseCreated(event.data);
break;
case 'kyb.case.status.changed':
handleStatusChanged(event.data);
break;
case 'kyb.case.completed':
handleCaseCompleted(event.data);
break;
case 'kyb.case.rejected':
handleCaseRejected(event.data);
break;
case 'kyb.ubo.invited':
handleUboInvited(event.data);
break;
case 'kyb.ubo.completed':
handleUboCompleted(event.data);
break;
default:
console.log('Unknown event type:', event.type);
}
// Return 200 to acknowledge receipt
res.status(200).send('OK');
});
function handleCaseCreated(data) {
console.log('New KYB case created:', data.caseId);
// Update your database, send notifications, etc.
}
function handleStatusChanged(data) {
console.log(`Case ${data.caseId} status changed from ${data.oldStatus} to ${data.newStatus}`);
// Update your database with new status
}
function handleCaseCompleted(data) {
console.log('Case completed:', data.caseId);
// Enable business account, grant access, etc.
}
function handleCaseRejected(data) {
console.log('Case rejected:', data.caseId, 'Reason:', data.rejectionReason);
// Notify business customer, request additional information, etc.
}
function handleUboInvited(data) {
console.log(`UBO ${data.uboRefId} invited for case ${data.caseId}`);
// Track UBO invitation in your system
}
function handleUboCompleted(data) {
console.log(`UBO ${data.uboRefId} completed verification for case ${data.caseId}`);
// Update UBO status in your database
}
app.listen(3000, () => {
console.log('Webhook server listening on port 3000');
});
import os
import hmac
import hashlib
from flask import Flask, request, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = os.environ['VOVE_WEBHOOK_SECRET']
def verify_webhook_signature(payload, signature, secret):
"""Verify the webhook signature"""
expected_signature = hmac.new(
secret.encode(),
payload.encode(),
hashlib.sha256
).digest().hex()
return hmac.compare_digest(signature, expected_signature)
@app.route('/webhooks/vove-kyb', methods=['POST'])
def webhook_handler():
# Get signature from header
signature = request.headers.get('svix-signature')
# Verify signature
if not verify_webhook_signature(request.data.decode(), signature, WEBHOOK_SECRET):
return jsonify({'error': 'Invalid signature'}), 401
event = request.json
event_type = event['type']
data = event['data']
# Handle different event types
if event_type == 'kyb.case.created':
handle_case_created(data)
elif event_type == 'kyb.case.status.changed':
handle_status_changed(data)
elif event_type == 'kyb.case.completed':
handle_case_completed(data)
elif event_type == 'kyb.case.rejected':
handle_case_rejected(data)
elif event_type == 'kyb.ubo.invited':
handle_ubo_invited(data)
elif event_type == 'kyb.ubo.completed':
handle_ubo_completed(data)
return jsonify({'status': 'success'}), 200
def handle_case_created(data):
print(f"New KYB case created: {data['caseId']}")
# Update your database, send notifications, etc.
def handle_status_changed(data):
print(f"Case {data['caseId']} status changed from {data.get('oldStatus')} to {data['newStatus']}")
# Update your database with new status
def handle_case_completed(data):
print(f"Case completed: {data['caseId']}")
# Enable business account, grant access, etc.
def handle_case_rejected(data):
print(f"Case rejected: {data['caseId']}, Reason: {data['rejectionReason']}")
# Notify business customer, request additional information, etc.
def handle_ubo_invited(data):
print(f"UBO {data['uboRefId']} invited for case {data['caseId']}")
# Track UBO invitation in your system
def handle_ubo_completed(data):
print(f"UBO {data['uboRefId']} completed verification for case {data['caseId']}")
# Update UBO status in your database
if __name__ == '__main__':
app.run(port=3000)
const processedEvents = new Set();
app.post('/webhooks/vove-kyb', (req, res) => {
const eventId = req.body.id;
// Check if we've already processed this event
if (processedEvents.has(eventId)) {
console.log('Event already processed:', eventId);
return res.status(200).send('OK');
}
// Process the event
handleWebhookEvent(req.body);
// Mark as processed
processedEvents.add(eventId);
res.status(200).send('OK');
});
# Install ngrok
npm install -g ngrok
# Start your webhook server locally
node webhook-server.js
# In another terminal, start ngrok
ngrok http 3000
# Use the ngrok HTTPS URL in VOVE ID dashboard
# Example: https://abc123.ngrok.io/webhooks/vove-kyb
async function handleStatusChanged(data) {
await database.kybCases.update(
{ refId: data.caseRefId },
{
status: data.newStatus,
updatedAt: new Date(data.changedAt)
}
);
console.log(`Updated case ${data.caseRefId} to status ${data.newStatus}`);
}
async function handleCaseCompleted(data) {
// Update business status
await database.businesses.update(
{ refId: data.caseRefId },
{
verified: true,
verifiedAt: new Date(data.completedAt),
accountStatus: 'ACTIVE'
}
);
// Send notification email
await emailService.send({
to: business.email,
subject: 'Business Verification Complete',
template: 'business-verified'
});
// Grant access to platform features
await grantBusinessAccess(data.caseRefId);
}
async function handleCaseRejected(data) {
const business = await database.businesses.findOne({ refId: data.caseRefId });
// Send notification with rejection reason
await emailService.send({
to: business.email,
subject: 'Business Verification Requires Attention',
template: 'business-rejected',
data: {
rejectionReason: data.rejectionReason,
reviewNotes: data.reviewNotes,
supportLink: 'https://support.example.com'
}
});
}
async function handleUboCompleted(data) {
// Update UBO status
await database.ubos.update(
{ refId: data.uboRefId, caseId: data.caseId },
{ status: 'COMPLETED', completedAt: new Date(data.completedAt) }
);
// Check if all UBOs are complete
const allUbos = await database.ubos.find({ caseId: data.caseId });
const allComplete = allUbos.every(ubo => ubo.status === 'COMPLETED');
if (allComplete) {
console.log(`All UBOs completed for case ${data.caseId}`);
// Trigger next step in your workflow
}
}
