> ## 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.

# Register Webhook

> Register a webhook URL to receive HMAC-SHA256-signed POST payloads when AIOKA events occur.

## Overview

Register a callback URL to receive signed event payloads whenever AIOKA events occur. Each delivery includes a `X-AIOKA-Signature: sha256=<hex>` header you can use to verify authenticity.

**Tier:** Basic 🔒
**Limit:** 5 webhooks per API key
**Delivery:** HMAC-SHA256 signed via `X-AIOKA-Signature: sha256=<hex>` header
**Retries:** Up to 3 attempts with exponential backoff (5s, 25s, 125s)
**Auto-disable:** After 10 consecutive failures, the webhook is deactivated

## Supported Events

| Event           | Trigger                                                           |
| :-------------- | :---------------------------------------------------------------- |
| `verdict.new`   | New Judiciary verdict produced                                    |
| `council.new`   | New AI Council verdict produced                                   |
| `regime.change` | Market regime changed                                             |
| `ghost.signal`  | Ghost Trader detects entry opportunity (BTC, ETH, SOL, TAO, GOLD) |
| `ghost.tp1`     | Ghost Trader TP1 partial sell executed (any asset)                |
| `ghost.closed`  | Ghost Trader trade fully closed (any asset)                       |
| `macro.alert`   | Macro correlation crosses ±0.15 threshold                         |

## Request

<ParamField body="url" type="string" required>
  The HTTPS URL to deliver payloads to. Must start with `https://`.
</ParamField>

<ParamField body="events" type="array" required>
  List of event types to subscribe to. Must contain at least 1 and at most 5 items. Duplicates are rejected.
</ParamField>

## Response

<ResponseField name="id" type="string">
  UUID of the webhook subscription.
</ResponseField>

<ResponseField name="url" type="string">
  The registered HTTPS callback URL.
</ResponseField>

<ResponseField name="events" type="array">
  List of subscribed event types.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the webhook is currently active.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="secret" type="string">
  **Shown only once.** The HMAC signing secret. Store it securely -- it cannot be retrieved again.
</ResponseField>

<ResponseField name="failures_since_success" type="integer">
  Number of consecutive delivery failures since last success.
</ResponseField>

## Verifying Signatures

On receipt, verify every delivery using the secret shown at registration:

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

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

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.aioka.io/v1/webhooks \
    -H "X-API-Key: aik_basic_..." \
    -H "Content-Type: application/json" \
    -d '{"url": "https://your-server.com/aioka-hook", "events": ["verdict.new", "ghost.signal"]}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-server.com/aioka-hook",
    "events": ["verdict.new", "ghost.signal"],
    "is_active": true,
    "created_at": "2026-04-18T10:00:00Z",
    "last_triggered_at": null,
    "failures_since_success": 0,
    "secret": "a1b2c3d4e5f6..."
  }
  ```
</ResponseExample>