Webhooks

Get notified in real-time when a fraud check returns BLOCK or REVIEW. Webhooks are HMAC-SHA256 verified and delivered with retry logic. Configure once, receive forever.

Setup

Add your webhook URL in your dashboard. We send a POST request to your endpoint on every BLOCK or REVIEW verdict.

Payload format

POST https://your-app.com/webhooks/kairos
Content-Type: application/json
X-Kairos-Signature: sha256=abc123...
X-Kairos-Event: check.blocked

{
  "event": "check.blocked",
  "timestamp": "2026-05-15T14:32:00.000Z",
  "data": {
    "query": "paypal-account-suspended.store",
    "type": "domain",
    "verdict": "BLOCK",
    "score": 100,
    "signals": ["domain:brand-impersonation:paypal", "domain:high-risk-tld:.store"],
    "ref": "a1b2c3d4"
  }
}

Verifying the signature

Always verify the X-Kairos-Signature header before processing a webhook. This prevents attackers from sending fake events to your endpoint.

// Node.js verification
const crypto = require('crypto');

function verifyKairosWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/webhooks/kairos', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-kairos-signature'];
  if (!verifyKairosWebhook(req.body, sig, process.env.KC_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.json({ received: true });
});

Events

Retry policy

If your endpoint returns anything other than 2xx, we retry up to 3 times with exponential backoff (1s, 4s, 16s). After 3 failures, the event is marked as failed in your dashboard.