Event Types

Complete reference for all webhook events.

Trust Events

trust.miscalibrated

Fired when a user shows automation bias or algorithm aversion.

Payload:

{
  "event": "trust.miscalibrated",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "user_id": "user_123",
    "calibration": "OVERTRUSTING",
    "previous_calibration": "WELL_CALIBRATED",
    "severity": "high",
    "trust_score": 0.45,
    "total_decisions": 89,
    "automation_bias_incidents": 12,
    "recommendation": "Immediate intervention required (EU AI Act Article 14)",
    "regulation_mapping": {
      "eu_ai_act": "Article 14(4)(b)",
      "texas_traiga": "§ 2056.002"
    }
  },
  "idempotency_key": "idem_abc123"
}

Calibration Values:

• OVERTRUSTING — Automation bias detected

• UNDERTRUSTING — Algorithm aversion detected

• INCONSISTENT — Erratic trust patterns

---

Bias Events

bias.detected

Fired when demographic bias is detected.

Payload:

{
  "event": "bias.detected",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "bias_type": "accuracy_disparity",
    "affected_subgroup": "age_group:65+",
    "severity": "high",
    "disparity_percentage": 25,
    "sample_size": 89,
    "affected_users": 12,
    "ai_accuracy_overall": 0.85,
    "ai_accuracy_subgroup": 0.62,
    "recommendation": "Immediate review required (FDA AI/ML Section IV)",
    "regulation_mapping": {
      "eu_ai_act": "Article 10",
      "fda": "Section IV.B"
    }
  },
  "idempotency_key": "idem_def456"
}

Bias Types:

• accuracy_disparity — AI less accurate for group

• representation_disparity — Group underrepresented

• treatment_disparity — Different treatment for similar cases

Severity Levels:

• high — Disparity >20% or >100 users

• medium — Disparity 10-20% or 50-100 users

• low — Disparity <10% or <50 users

---

Risk Events

risk_user.identified

Fired when a user is flagged as high-risk.

Payload:

{
  "event": "risk_user.identified",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "user_id": "user_456",
    "risk_level": "high",
    "risk_factors": [
      "automation_bias_pattern",
      "declining_override_quality",
      "fast_decision_time"
    ],
    "trust_score": 0.38,
    "calibration": "OVERTRUSTING",
    "recommendation": "Mandatory training required"
  },
  "idempotency_key": "idem_ghi789"
}

Risk Levels:

• high — Immediate attention required

• medium — Review within 7 days

• low — Monitor

---

threshold.breached

Fired when a custom threshold is exceeded.

Payload:

{
  "event": "threshold.breached",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "threshold_id": "thresh_abc123",
    "threshold_name": "Override Rate Minimum",
    "threshold_value": 0.15,
    "actual_value": 0.08,
    "direction": "below",
    "user_id": "user_789",
    "time_window": "7d"
  },
  "idempotency_key": "idem_jkl012"
}

---

Compliance Events

audit.required

Fired when a regulatory audit is triggered.

Payload:

{
  "event": "audit.required",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "regulation": "texas_traiga",
    "requirement": "§ 2056.103",
    "reason": "semi_annual_audit_due",
    "due_date": "2026-01-15",
    "affected_decisions": 12456,
    "recommendation": "Generate Texas TRAIGA compliance report"
  },
  "idempotency_key": "idem_mno345"
}

---

compliance.report_ready

Fired when an export is complete.

Payload:

{
  "event": "compliance.report_ready",
  "timestamp": "2025-12-25T10:05:00Z",
  "data": {
    "export_id": "exp_abc123",
    "template": "eu_ai_act",
    "format": "pdf",
    "file_size_bytes": 245000,
    "download_url": "https://exports.athenatrust.ai/exp_abc123.pdf",
    "expires_at": "2025-12-26T10:00:00Z"
  },
  "idempotency_key": "idem_pqr678"
}

---

Subscribing to Events

When creating a webhook, specify which events to receive:

{
  "url": "https://your-app.com/webhook",
  "events": [
    "trust.miscalibrated",
    "bias.detected",
    "risk_user.identified"
  ]
}

Subscribe to all events:

{
  "url": "https://your-app.com/webhook",
  "events": ["*"]
}

---

Next: Signature Verification