> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verify-group.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Register webhook endpoints, verify HMAC-SHA256 signatures, and handle Verify Group retries with exponential backoff for real-time API events.

## Register a webhook

```bash theme={null}
POST /api/v1/webhooks
```

```json theme={null}
{
  "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:

```typescript theme={null}
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));
}
```

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

## 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.

<Warning>Your endpoint must respond within **30 seconds**, or we mark the delivery failed.</Warning>