Webhooks
Webhooks notify your systems when important events happen — key errors, earnings, payouts, and rotation updates. Configure endpoints in the dashboard under Settings → Webhooks.
Available events
| Event | Trigger | Timing |
|---|---|---|
| key.error | A request routed through your key returned an error from the upstream provider | Immediate |
| key.degraded | Your key's priority score dropped below 0.3 | Immediate |
| key.inactive | Your key was revoked or its request budget was exhausted | Immediate |
| key.liveness_failed | A scheduled liveness re-check failed | Immediate |
| key.rotation_started | A key rotation overlap window began | Immediate |
| key.rotation_complete | A key rotation finished and the new key was promoted | Immediate |
| payout.created | A payout was queued for processing | Immediate |
| payout.completed | A payout was confirmed by the payment provider | Immediate |
| payout.failed | A payout attempt failed | Immediate |
| earning.batch_credited | New earnings accumulated | Every 5 min |
The earning.batch_credited event is batched every 5 minutes to avoid overwhelming your endpoint with per-request events. It includes a summary of earnings grouped by provider.
Payload format
Every webhook delivery is a POST request with a JSON body:
{
"id": "del_abc123",
"event": "key.error",
"timestamp": "2025-03-20T14:32:00Z",
"sellerId": "sel_xyz",
"data": {
// event-specific fields
}
}Verifying signatures
Every webhook includes an X-CN2-Signature header containing an HMAC-SHA256 signature of the raw request body, computed with your endpoint's secret.
X-CN2-Signature: sha256=a1b2c3...
To verify: compute HMAC-SHA256 of the raw body using your endpoint secret, then compare with the header value. Reject requests where the signature does not match.
Retries
If your endpoint returns a non-2xx status, cn2.ai retries with exponential backoff:
- Immediately
- After 1 minute
- After 5 minutes
- After 30 minutes
- After 2 hours (final attempt)
If your endpoint has been failing continuously for more than 1 hour, you receive an email notification. Webhooks are never auto-disabled — you manage delivery status in the dashboard.