Webhooks

Receive and process VOVE ID webhooks with Svix signature verification.

VOVE ID sends HTTPS webhook requests when verification, KYB, or AML resources change. Verify every request before parsing or processing it.

Configure an endpoint

1. Open Webhooks in the matching Sandbox or Production dashboard.

2. Add a publicly reachable HTTPS endpoint.

3. Select the event types required by your integration.

4. Store the generated signing secret in your server secret manager.

5. Send or replay a fictional Sandbox event.

Sandbox and Production endpoints use separate signing secrets.

Request headers

Header	Type	Description
svix-id	string	Unique delivery identifier; use it for idempotency
svix-timestamp	string	Signed delivery timestamp
svix-signature	string	One or more versioned signatures
content-type	string	application/json

Header names are case-insensitive. Frameworks commonly expose them in lowercase.

Representative KYC event

POST /webhooks/vove HTTP/1.1
Host: example.test
Content-Type: application/json
Svix-Id: msg_example_01
Svix-Timestamp: 1788775200
Svix-Signature: v1,example_signature

{
  "status": "successful",
  "refId": "customer-7f3d",
  "userId": "customer-7f3d"
}

Deprecated: userId is retained only for backward compatibility and will be removed in a future version. Use refId to identify and correlate users.

Verify the raw request body

Install the official Svix package:

npm install svix

Node.js and Express

import express from 'express';
import { Webhook } from 'svix';

const app = express();

// Register this route before app.use(express.json()).
app.post('/webhooks/vove', express.raw({ type: 'application/json' }), async (req, res) => {
  const headers = {
    'svix-id': req.header('svix-id'),
    'svix-timestamp': req.header('svix-timestamp'),
    'svix-signature': req.header('svix-signature'),
  };

  let event;

  try {
    event = new Webhook(process.env.VOVE_WEBHOOK_SECRET).verify(req.body, headers);
  } catch {
    return res.sendStatus(400);
  }

  const deliveryId = headers['svix-id'];
  await persistAndEnqueueOnce(deliveryId, event);

  return res.sendStatus(204);
});

The verifier must receive the original bytes. express.json() changes the body representation, which makes signature verification fail.

Python and Flask

import os

from flask import Flask, request
from svix.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)

@app.post("/webhooks/vove")
def receive_vove_webhook():
    payload = request.get_data()
    headers = {
        "svix-id": request.headers.get("svix-id"),
        "svix-timestamp": request.headers.get("svix-timestamp"),
        "svix-signature": request.headers.get("svix-signature"),
    }

    try:
        event = Webhook(os.environ["VOVE_WEBHOOK_SECRET"]).verify(
            payload,
            headers,
        )
    except WebhookVerificationError:
        return "", 400

    persist_and_enqueue_once(headers["svix-id"], event)
    return "", 204

Processing contract

1. Read the unmodified request bytes.

2. Verify the timestamp and signature with the official library.

3. Deduplicate on svix-id using durable storage and a unique constraint.

4. Store the verified event and enqueue work in one transaction where possible.

5. Return 200 or 204 quickly.

6. Process asynchronously.

7. Tolerate duplicates and out-of-order delivery.

8. Retrieve the current API resource before applying a consequential decision.

Do not deduplicate on refId because one subject can produce multiple legitimate events.

Event payload types

type KycWebhookPayload = {
  refId: string;
  status:
    | 'in_progress'
    | 'pending'
    | 'successful'
    | 'suspected'
    | string;
  userId?: string;
  [field: string]: unknown;
};

type KybWebhookPayload = {
  refId: string;
  status:
    | 'IN_PROGRESS'
    | 'IN_REVIEW'
    | 'COMPLETED'
    | 'REJECTED'
    | string;
  previousStatus?: string;
  reason?: string;
  [field: string]: unknown;
};

See Statuses and KYB webhooks for exact event mappings.

Retries and ordering

Webhook delivery can be retried and replayed. Your handler must be safe when:

• The same delivery arrives more than once.

• A newer resource state arrives before an older event.

• Your worker fails after the endpoint has acknowledged the request.

• The endpoint times out after persisting the event.

Do not depend on a fixed retry schedule. Use the delivery log for diagnosis and retrieve the current API resource during reconciliation.

Test the endpoint

Test all of these cases in Sandbox:

Test	Expected result
Valid event	200 or 204 and one queued action
Altered body	400
Missing or invalid signature	400
Same svix-id twice	One business action
Worker failure	Event remains available for retry
Out-of-order status	Current API resource wins

For local testing, expose the server through an HTTPS tunnel, register the temporary URL in Sandbox, and use the dashboard's send or replay function. Never use a Production signing secret in local tooling.

Safe logging

Log event type, svix-id, refId, processing result, latency, and your correlation ID. Do not log the signing secret, signature, session token, raw payload, documents, biometrics, or unredacted personal or match data.

Troubleshooting

Problem	Likely cause	Resolution
Every signature fails	Body parsed before verification	Configure a raw-body route before JSON middleware
Some signatures fail	Wrong environment secret or altered proxy body	Check endpoint configuration and proxy behavior
Repeated deliveries	Non-2xx response or timeout	Acknowledge after durable enqueueing
Duplicate business action	No durable svix-id uniqueness	Add a unique constraint and transactional enqueue
Status appears to go backwards	Out-of-order delivery	Retrieve the current resource and compare timestamps/state