Skip to main content
POST
/
v1
/
webhooks
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"]}'

{
  "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..."
}

​
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

EventTrigger
verdict.newNew Judiciary verdict produced
council.newNew AI Council verdict produced
regime.changeMarket regime changed
ghost.signalGhost Trader detects entry opportunity (BTC, ETH, SOL, TAO, GOLD)
ghost.tp1Ghost Trader TP1 partial sell executed (any asset)
ghost.closedGhost Trader trade fully closed (any asset)
macro.alertMacro correlation crosses ±0.15 threshold

​
Request

​
url
string
required
The HTTPS URL to deliver payloads to. Must start with https://.
​
events
array
required
List of event types to subscribe to. Must contain at least 1 and at most 5 items. Duplicates are rejected.

​
Response

​
id
string
UUID of the webhook subscription.
​
url
string
The registered HTTPS callback URL.
​
events
array
List of subscribed event types.
​
is_active
boolean
Whether the webhook is currently active.
​
created_at
string
ISO 8601 creation timestamp.
​
secret
string
Shown only once. The HMAC signing secret. Store it securely — it cannot be retrieved again.
​
failures_since_success
integer
Number of consecutive delivery failures since last success.

​
Verifying Signatures

On receipt, verify every delivery using the secret shown at registration: 
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)

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"]}'

{
  "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..."
}