Webhooks API

Receive real-time notifications about security events.

Create Webhook

POST /v1/webhooks
curl https://api.talonai.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/talonai",
    "events": ["threat.detected", "policy.violated"],
    "secret": "your-webhook-secret"
  }'

Webhook Events

EventDescription
threat.detectedHigh-risk content detected
threat.blockedRequest was blocked
policy.violatedPolicy rule triggered
pii.detectedPII found in content
rate_limit.exceededRate limit hit

Webhook Payload

{
  "id": "evt_abc123",
  "type": "threat.detected",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "analysisId": "analysis_xyz789",
    "riskScore": 85,
    "riskLevel": "high",
    "threats": [
      {
        "type": "prompt_injection",
        "confidence": 0.92,
        "description": "Detected instruction override attempt"
      }
    ],
    "content": "[truncated]",
    "metadata": {
      "userId": "user_123",
      "sessionId": "sess_abc"
    }
  }
}

Verifying Webhooks

Verify webhook signatures to ensure authenticity:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express handler
app.post('/webhooks/talonai', (req, res) => {
  const signature = req.headers['x-talonai-signature'];

  if (!verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

Best Practices

  • Always verify webhook signatures
  • Respond with 200 quickly, process async
  • Implement idempotency using event IDs
  • Set up retry handling for failures