Webhooks

X-KYC-Signature: sha256=<hex-hmac-of-body>

{
  "type": "submission.created | verification.completed | verification.failed",
  "id": "<eventType>:<submissionId>",
  "timestamp": "2025-08-10T21:50:43.235Z",
  "status": "Approved | Submitted | Declined",
  "data": {
    "session": {
      "id": "<sessionId>",
      "status": "Approved | Submitted | Declined",
      "kycStatus": "not_started | processing | completed | failed",
      "redirectUrl": "https://...",
      "metadata": {},
      "createdAt": { "_seconds": 0, "_nanoseconds": 0 },
      "updatedAt": { "_seconds": 0, "_nanoseconds": 0 },
      "images": {
        "documentFrontUrl": "https://...",
        "documentBackUrl": "https://...",
        "selfieUrls": ["https://...", "https://...", "https://..."]
      }
    },
    "submission": {
      "id": "<submissionId>",
      "sessionId": "<sessionId>",
      "workspaceId": "<workspaceId>",
      "pass": true,
      "expectedDocumentType": "passport | id-card",
      "detectedDocumentType": "passport | id-card | unknown",
      "document": {},
      "face": {},
      "overall": { "pass": true, "reasons": [], "user_message": null },
      "kycStatus": "Approved | Submitted | Declined",
      "createdAt": { "_seconds": 0, "_nanoseconds": 0 }
    }
  }
}

POST /v1/kyc/webhooks/test

{ "workspaceId": "<workspaceId>" }

import type { NextApiRequest, NextApiResponse } from 'next';
import crypto from 'crypto';

function verifySignature(rawBody: string, header: string | undefined, secret: string) {
  if (!header) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  const signature = req.headers['x-kyc-signature'] as string | undefined;
  const secret = process.env.KYC_WEBHOOK_SECRET || '';
  const raw = (req as any).rawBody ?? JSON.stringify(req.body);
  if (!verifySignature(raw, signature, secret)) return res.status(401).json({ error: 'invalid_signature' });

  const evt = req.body as { type: string; id: string; timestamp: string; data: any };

  // idempotent handling
  // upsert evt.id to a processed store before acting

  switch (evt.type) {
    case 'submission.created':
      break;
    case 'verification.completed':
      break;
    case 'verification.failed':
      break;
    default:
      // ignore
  }

  return res.status(200).json({ received: true });
}