Webhooks - Verify Group

Register a webhook

POST /api/v1/webhooks

{
  "url": "https://your-system.io/webhooks/verify-group",
  "events": ["kyc.verified", "claim.status_changed", "sanctions.match.detected"],
  "secret": "whsec_your_signing_secret"
}

Verify signatures

Every delivery includes X-VG-Signature-256. Always verify before processing:

import crypto from "crypto";

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = `sha256=${crypto.createHmac("sha256", secret).update(rawBody).digest("hex")}`;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Parse the body as raw bytes before verifying — parsing JSON first changes the byte representation and breaks signature checks.

Retry policy

We retry failed deliveries with exponential backoff: 5s → 30s → 5m → 30m → 2h. After 5 failures, we mark the webhook failed and send you an email alert.

Your endpoint must respond within 30 seconds, or we mark the delivery failed.