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

---

model.bias.ingested (v1.1.0)

Fired when an external fairness signal is successfully ingested.

Payload:

{
  "event": "model.bias.ingested",
  "timestamp": "2025-12-27T10:30:00Z",
  "data": {
    "signal_id": "sig_abc123",
    "model_id": "loan-approval-v3",
    "external_tool_id": "ibm_aif360",
    "external_tool_version": "0.6.1",
    "metric_name": "demographic_parity",
    "metric_value": 0.42,
    "passes_threshold": true,
    "protected_attribute": "gender",
    "privileged_group": "male",
    "unprivileged_group": "female"
  },
  "idempotency_key": "idem_sig123"
}

---

bias.amplification (v1.1.0)

Fired when ATHENA detects that human behavior is amplifying model bias. Only triggered when severity is high or critical.

Payload:

{
  "event": "bias.amplification",
  "timestamp": "2025-12-27T10:35:00Z",
  "data": {
    "alert_id": "alert_xyz789",
    "model_id": "loan-approval-v3",
    "fairness_signal_id": "sig_abc123",
    "amplification_score": 0.68,
    "amplification_type": "overtrust",
    "severity": "high",
    "protected_attribute": "gender",
    "affected_subgroup": "female",
    "overtrust_rate": 0.42,
    "undertrust_rate": 0.08,
    "correlated_decisions": 156,
    "message": "42% of decisions overtrusted biased AI recommendations for female applicants",
    "recommendation": "Immediate review of approval workflow for affected demographic",
    "regulation_mapping": {
      "eu_ai_act": "Article 14(4)(b)",
      "colorado_ai_act": "§ 1702(3)"
    }
  },
  "idempotency_key": "idem_alert789"
}

Amplification Types:

• overtrust — Humans blindly following biased AI

• undertrust — Humans rejecting accurate AI for certain groups

• mixed — Both patterns detected

When This Fires: This event only fires when severity >= high. Lower severity amplifications are logged but do not trigger webhooks.

---

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",
    "bias.amplification",
    "model.bias.ingested",
    "risk_user.identified"
  ]
}

Subscribe to all events:

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

---

Next: Signature Verification