KYB Webhooks

Real-time KYB Event Notifications

Overview

VOVE ID uses webhooks to send real-time notifications about KYB case status changes to your application. Webhooks allow you to receive immediate updates when a case moves into progress, enters review, is completed, or is rejected, 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

1. Log in to the VOVE ID dashboard

2. Navigate to Settings → Webhooks

3. Add your webhook endpoint URL (must be HTTPS)

4. Select which event types you want to receive

5. 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.in_progress

Triggered when a KYB case moves into IN_PROGRESS.

Payload:

{
  "refId": "unique-business-ref-12345",
  "status": "IN_PROGRESS",
  "previousStatus": "NOT_STARTED"
}

kyb.case.in_review

Triggered when a KYB case moves into IN_REVIEW.

Payload:

{
  "refId": "unique-business-ref-12345",
  "status": "IN_REVIEW",
  "previousStatus": "IN_PROGRESS"
}

kyb.case.completed

Triggered when a case is approved and marked as completed.

Payload:

{
  "refId": "unique-business-ref-12345",
  "status": "COMPLETED",
  "previousStatus": "IN_REVIEW"
}

kyb.case.rejected

Triggered when a case is rejected.

Payload:

{
  "refId": "unique-business-ref-12345",
  "status": "REJECTED",
  "previousStatus": "IN_REVIEW",
  "reason": "DOCUMENT_MISMATCH"
}

kyb.case.created is not currently emitted as an external webhook. Webhooks begin once the case status changes from NOT_STARTED.

Implementing Webhook Handlers

Node.js/Express Example

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 status changes from the webhook payload
  switch (event.status) {
    case 'IN_PROGRESS':
      handleCaseInProgress(event);
      break;

    case 'IN_REVIEW':
      handleCaseInReview(event);
      break;

    case 'COMPLETED':
      handleCaseCompleted(event);
      break;

    case 'REJECTED':
      handleCaseRejected(event);
      break;

    default:
      console.log('Unknown KYB webhook payload:', event);
  }

  // Return 200 to acknowledge receipt
  res.status(200).send('OK');
});

function handleCaseInProgress(data) {
  console.log('Case is now in progress:', data.refId);
  // Record that the customer started the KYB flow
}

function handleCaseInReview(data) {
  console.log('Case is now in review:', data.refId);
  // Update your database with the latest review status
}

function handleCaseCompleted(data) {
  console.log('Case completed:', data.refId);
  // Enable business account, grant access, etc.
}

function handleCaseRejected(data) {
  console.log('Case rejected:', data.refId, 'Reason:', data.reason);
  // Notify business customer, request additional information, etc.
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Python/Flask Example

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

    payload = request.json
    status = payload.get('status')

    if status == 'IN_PROGRESS':
        handle_case_in_progress(payload)
    elif status == 'IN_REVIEW':
        handle_case_in_review(payload)
    elif status == 'COMPLETED':
        handle_case_completed(payload)
    elif status == 'REJECTED':
        handle_case_rejected(payload)

    return jsonify({'status': 'success'}), 200

def handle_case_in_progress(data):
    print(f"Case in progress: {data['refId']}")
    # Record that the customer started the KYB flow

def handle_case_in_review(data):
    print(f"Case in review: {data['refId']}")
    # Update your database with the latest review status

def handle_case_completed(data):
    print(f"Case completed: {data['refId']}")
    # Enable business account, grant access, etc.

def handle_case_rejected(data):
    print(f"Case rejected: {data['refId']}, Reason: {data.get('reason')}")
    # Notify business customer, request additional information, etc.

if __name__ == '__main__':
    app.run(port=3000)

Security Best Practices

Signature Verification

Always verify webhook signatures to ensure the request is from VOVE ID:

1. Get the svix-signature header from the request

2. Compute the expected signature using your webhook secret

3. Compare the signatures using a timing-safe comparison

4. Reject requests with invalid signatures

Idempotency

Webhooks may be delivered more than once. Implement idempotency handling:

const processedEvents = new Set();

app.post('/webhooks/vove-kyb', (req, res) => {
  const eventId = req.headers['svix-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');
});

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

app.post('/webhooks/vove-kyb', async (req, res) => {
  try {
    await processWebhookEvent(req.body);
    res.status(200).send('OK');
  } catch (error) {
    if (error.name === 'ValidationError') {
      // Client error, don't retry
      res.status(400).send('Invalid data');
    } else {
      // Server error, allow retry
      res.status(500).send('Internal error');
    }
  }
});

Timeout Handling

Respond quickly (within 15 seconds) to avoid timeouts:

app.post('/webhooks/vove-kyb', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookEventAsync(req.body)
    .catch(error => {
      console.error('Error processing webhook:', error);
    });
});

Testing Webhooks

Local Development with ngrok

Use ngrok to expose your local server for webhook testing:

# 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

Testing with cURL

Simulate webhook events locally:

curl -X POST http://localhost:3000/webhooks/vove-kyb \
  -H "Content-Type: application/json" \
  -H "svix-signature: your-test-signature" \
  -d '{
    "refId": "test-ref-id",
    "status": "COMPLETED",
    "previousStatus": "IN_REVIEW"
  }'

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:

app.post('/webhooks/vove-kyb', (req, res) => {
  const eventId = req.headers['svix-id'];
  const status = req.body.status;

  console.log('Webhook received:', {
    eventId,
    status,
    timestamp: new Date().toISOString()
  });

  try {
    handleWebhookEvent(req.body);

    console.log('Webhook processed successfully:', eventId);
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook processing error:', {
      eventId,
      error: error.message,
      stack: error.stack
    });
    res.status(500).send('Error');
  }
});

Common Use Cases

Update Case Status in Database

async function handleStatusChanged(data) {
  await database.kybCases.update(
    { refId: data.refId },
    {
      status: data.status,
      previousStatus: data.previousStatus,
      updatedAt: new Date()
    }
  );

  console.log(`Updated case ${data.refId} to status ${data.status}`);
}

Enable Business Account on Completion

async function handleCaseCompleted(data) {
  // Update business status
  await database.businesses.update(
    { refId: data.refId },
    {
      verified: true,
      verifiedAt: new Date(),
      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.refId);
}

Notify Customer on Rejection

async function handleCaseRejected(data) {
  const business = await database.businesses.findOne({ refId: data.refId });

  // Send notification with rejection reason
  await emailService.send({
    to: business.email,
    subject: 'Business Verification Requires Attention',
    template: 'business-rejected',
    data: {
      rejectionReason: data.reason,
      supportLink: 'https://support.example.com'
    }
  });
}

Related Documentation

• KYB Overview - Understand the KYB verification flow

• Create KYB Case - Learn how to create cases

• KYB Case Management - Manage cases and UBOs

• Webhooks (General) - General webhook documentation