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