Webhooks

Real-time event notifications with HMAC-SHA256 signature verification.

POST /webhooks

Create a new webhook endpoint.

Request

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

Field	Type	Required	Description
url	string	✅	HTTPS endpoint URL
events	array	✅	Events to subscribe to
description	string	❌	Webhook description

Response

{
  "webhook_id": "wh_abc123",
  "url": "https://your-app.com/athena-webhook",
  "secret": "whsec_xyz789",
  "events": ["trust.miscalibrated", "bias.detected"],
  "created_at": "2025-12-25T10:00:00Z"
}

Important: The secret is shown only once. Store it securely — you'll need it to verify webhook signatures.

Example

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": ["trust.miscalibrated", "bias.detected"]
  }'

---

GET /webhooks

List all webhooks.

Response

{
  "webhooks": [
    {
      "webhook_id": "wh_abc123",
      "url": "https://your-app.com/athena-webhook",
      "events": ["trust.miscalibrated"],
      "status": "active",
      "created_at": "2025-12-25T10:00:00Z",
      "last_delivery_at": "2025-12-25T11:00:00Z"
    }
  ]
}

---

PATCH /webhooks/:id

Update a webhook.

Request

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

---

DELETE /webhooks/:id

Delete a webhook.

Response

{
  "deleted": true
}

---

POST /webhooks/:id/test

Send a test webhook event.

Response

{
  "test_id": "test_abc123",
  "status": "delivered",
  "response_code": 200,
  "response_time_ms": 145
}

---

POST /webhooks/:id/rotate-secret

Rotate webhook secret.

Response

{
  "new_secret": "whsec_new789",
  "old_secret_valid_until": "2025-12-26T10:00:00Z"
}

The old secret remains valid for 24 hours (grace period).

---

POST /webhooks/:id/enable

Re-enable a disabled webhook.

Response

{
  "webhook_id": "wh_abc123",
  "status": "active"
}

---

GET /webhooks/:id/deliveries

Get webhook delivery history.

Request

GET /webhooks/:id/deliveries?limit=50

Response

{
  "deliveries": [
    {
      "delivery_id": "del_123",
      "timestamp": "2025-12-25T10:00:00Z",
      "event": "trust.miscalibrated",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 145,
      "retry_count": 0
    },
    {
      "delivery_id": "del_124",
      "timestamp": "2025-12-25T09:00:00Z",
      "event": "bias.detected",
      "status": "failed",
      "response_code": 500,
      "retry_count": 3,
      "next_retry_at": "2025-12-25T10:00:00Z"
    }
  ]
}

---

Available Events

Event	Description	Regulation
trust.miscalibrated	User shows automation bias or algorithm aversion	EU Art 14(4)(b)
bias.detected	Bias detected across demographics	EU Art 10, FDA IV.B
risk_user.identified	User flagged as high-risk	All
threshold.breached	Custom threshold exceeded	All
audit.required	Regulatory audit triggered	Texas TRAIGA
compliance.report_ready	Export completed	All

---

Webhook Payload

All webhooks follow this format:

{
  "event": "trust.miscalibrated",
  "timestamp": "2025-12-25T10:00:00Z",
  "data": {
    "user_id": "user_123",
    "calibration": "OVERTRUSTING",
    "severity": "high",
    "recommendation": "Immediate intervention required"
  },
  "idempotency_key": "idem_abc123"
}

---

Signature Verification

All webhooks are signed using HMAC-SHA256.

Verify Signature

import { verifyWebhookSignature } from '@athena-ai/sdk';

app.post('/webhook', express.text({ type: '*/*' }), async (req, res) => {
  try {
    await verifyWebhookSignature(
      req.body,
      req.headers['x-athena-signature'],
      process.env.WEBHOOK_SECRET
    );
    
    const event = JSON.parse(req.body);
    console.log(`Event: ${event.event}`);
    
    res.sendStatus(200);
  } catch (error) {
    res.sendStatus(401);
  }
});

Signature Header Format

X-Athena-Signature: t=1703505600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

---

Retry Policy

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is disabled automatically.

---

Next: System Monitoring API