Overview

Receive real-time notifications when important events occur in your ATHENA account.

How Webhooks Work

1. Event occurs (e.g., bias detected)
2. ATHENA sends HTTPS POST to your endpoint
3. Your server processes the event
4. Respond with 2xx status code

Quick Setup

1. Create a Webhook

curl -X POST https://api.athenatrust.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/athena-webhook",
    "events": ["bias.detected", "trust.miscalibrated"]
  }'

2. Save the Secret

{
  "webhook_id": "wh_abc123",
  "secret": "whsec_xyz789"  // Save this!
}

3. Handle Events

app.post('/athena-webhook', (req, res) => {
  const event = req.body;
  
  switch(event.event) {
    case 'bias.detected':
      alertTeam(event.data);
      break;
    case 'trust.miscalibrated':
      scheduleIntervention(event.data);
      break;
  }
  
  res.sendStatus(200);
});

Webhook Payload

All webhooks follow this format:

{
  "event": "bias.detected",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "user_id": "user_123",
    "bias_type": "accuracy_disparity",
    "severity": "high",
    "affected_subgroup": "age_group:65+",
    "recommendation": "Immediate review required"
  },
  "idempotency_key": "idem_abc123"
}

Available Events

Event	Description	When Fired
trust.miscalibrated	User shows automation bias or algorithm aversion	Calibration analysis
bias.detected	Demographic bias detected	Bias detection
risk_user.identified	User flagged as high-risk	Trust scoring
threshold.breached	Custom threshold exceeded	Monitoring
audit.required	Regulatory audit triggered	Compliance check
compliance.report_ready	Export completed	Report generation

Security

All webhooks are signed using HMAC-SHA256. Always verify signatures before processing events.

See: Signature Verification

Reliability

Feature	Description
Retries	5 attempts with exponential backoff
Timeout	30 seconds per request
Ordering	Events delivered in order (best effort)
Idempotency	Use idempotency_key to dedupe

Best Practices

1. Respond quickly — Return 2xx within 30 seconds

2. Process async — Queue events for background processing

3. Verify signatures — Prevent spoofed events

4. Handle duplicates — Events may be delivered multiple times

5. Monitor delivery — Check webhook dashboard for failures

---

Next: Event Types