Webhooks

Delivery semantics

• One WebhookDelivery row is written before each attempt — the audit trail survives queue loss.
• Failed deliveries retry with exponential backoff for up to 5 attempts before the delivery is marked FAILED.
• A non-2xx response from your endpoint counts as failure; respond 200 as soon as you've verified the signature and enqueued your own processing.

Signature header

POST /your/webhook
Content-Type: application/json
X-Veridi-Signature: sha256=<hex hmac>
X-Veridi-Event-Id: evt_xxx
X-Veridi-Event-Type: kyc.completed

Verification (TypeScript)

import express from 'express';
import { parseWebhookEvent, VeridiError } from '@veridi/sdk';

const app = express();

app.post(
  '/webhooks/veridi',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = parseWebhookEvent({
        rawBody: req.body, // Buffer
        signatureHeader: req.get('x-veridi-signature'),
        secret: process.env.VERIDI_WEBHOOK_SECRET!,
      });

      switch (event.type) {
        case 'kyc.completed':
          // promote the user, unlock features, etc.
          break;
        case 'kyc.failed':
          // queue for manual review
          break;
      }
      res.status(200).end();
    } catch (err) {
      if (err instanceof VeridiError && err.code === 'ERR_WEBHOOK_002') {
        res.status(401).end();
        return;
      }
      res.status(500).end();
    }
  },
);

Verify-only (no parse)

import { verifyWebhookSignature } from '@veridi/sdk';

const ok = verifyWebhookSignature({
  rawBody: rawText,
  signatureHeader: req.headers['x-veridi-signature'],
  secret: webhookSecret,
});
if (!ok) return res.status(401).end();

Event catalog