> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time push events for verdicts, regime changes, and Ghost Trader signals — no polling required

# Webhooks

Webhooks let you subscribe to AIOKA events and receive HTTP POST notifications the moment something happens — no polling needed.

**Available to:** Basic tier and above (`$49/mo`)

***

## How It Works

1. Register a webhook endpoint URL with the event types you want to receive
2. AIOKA signs every delivery with an HMAC-SHA256 signature using your webhook secret
3. Your server verifies the signature and processes the payload
4. AIOKA retries failed deliveries up to 3 times with exponential backoff (5s → 25s → 125s)
5. A subscription is auto-disabled after 10 consecutive delivery failures

***

## Supported Events

| Event Type      | Trigger                                                              |
| --------------- | -------------------------------------------------------------------- |
| `verdict.new`   | New Judiciary ruling produced (every \~5 min cycle)                  |
| `council.new`   | New AI Council session completed (every \~30 min)                    |
| `regime.change` | Market regime transition detected                                    |
| `ghost.signal`  | Ghost Trader entry/exit signal fired                                 |
| `macro.alert`   | Cross-asset macro alert (Risk-Off Score ≥ 70, Fed hawkishness spike) |

***

## Registering a Webhook

```bash theme={null}
curl -X POST https://api.aioka.io/v1/webhooks \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/aioka-webhook",
    "events": ["verdict.new", "regime.change"]
  }'
```

Response includes your `webhook_secret` — **store it securely**. It is shown only once and cannot be retrieved later.

```json theme={null}
{
  "id": "wh_abc123",
  "url": "https://yourserver.com/aioka-webhook",
  "events": ["verdict.new", "regime.change"],
  "secret": "whsec_a1b2c3d4...",
  "is_active": true,
  "created_at": "2026-04-20T12:00:00Z"
}
```

***

## Verifying Signatures

Every delivery includes an `X-AIOKA-Signature` header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.

```python theme={null}
import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

**Always verify signatures** before processing a payload. Reject requests that fail verification with a `401`.

***

## Payload Format

All events share a common envelope:

```json theme={null}
{
  "event": "verdict.new",
  "timestamp": "2026-04-20T14:32:00Z",
  "data": { ... }
}
```

### `verdict.new`

```json theme={null}
{
  "event": "verdict.new",
  "timestamp": "2026-04-20T14:32:00Z",
  "data": {
    "ruling": "STRONG_BUY",
    "composite_score": 0.82,
    "confidence": 0.79,
    "regime": "BULL_TRENDING"
  }
}
```

### `council.new`

```json theme={null}
{
  "event": "council.new",
  "timestamp": "2026-04-20T14:00:00Z",
  "data": {
    "ruling": "BUY",
    "confidence": 0.76,
    "consensus_level": "STRONG",
    "agents_succeeded": 6
  }
}
```

### `regime.change`

```json theme={null}
{
  "event": "regime.change",
  "timestamp": "2026-04-20T13:45:00Z",
  "data": {
    "from_regime": "ACCUMULATION",
    "to_regime": "BULL_TRENDING",
    "confidence": 0.83
  }
}
```

***

## Limits

| Constraint                  | Value                        |
| --------------------------- | ---------------------------- |
| Max webhooks per API key    | 5                            |
| URL scheme                  | HTTPS only                   |
| Max retries on failure      | 3 (backoff: 5s → 25s → 125s) |
| Auto-disable after failures | 10 consecutive failures      |

***

## Managing Webhooks

| Action          | Endpoint                   |
| --------------- | -------------------------- |
| Register        | `POST /v1/webhooks`        |
| List all        | `GET /v1/webhooks`         |
| Delete          | `DELETE /v1/webhooks/{id}` |
| Send test event | `POST /v1/webhooks/test`   |

See the [API Reference → Webhooks](/api-reference/webhooks/register) section for full request/response schemas.

***

## Best Practices

* **Respond quickly.** Return `200` as soon as you receive the delivery. Do heavy processing asynchronously.
* **Verify signatures.** Never process a payload without first verifying the HMAC signature.
* **Handle duplicates.** On retry, the same event may be delivered more than once. Use the `event` + `timestamp` combination to deduplicate.
* **Store your secret securely.** Treat `whsec_*` like a password — never log it or expose it in client-side code.