Skip to main content

​
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 TypeTrigger
verdict.newNew Judiciary ruling produced (every ~5 min cycle)
council.newNew AI Council session completed (every ~30 min)
regime.changeMarket regime transition detected
ghost.signalGhost Trader entry/exit signal fired
macro.alertCross-asset macro alert (Risk-Off Score ≥ 70, Fed hawkishness spike)

​
Registering a Webhook

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. 
{
  "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. 
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: 
{
  "event": "verdict.new",
  "timestamp": "2026-04-20T14:32:00Z",
  "data": { ... }
}

​
verdict.new

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

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

​
regime.change

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

​
Limits

ConstraintValue
Max webhooks per API key5
URL schemeHTTPS only
Max retries on failure3 (backoff: 5s → 25s → 125s)
Auto-disable after failures10 consecutive failures

​
Managing Webhooks

ActionEndpoint
RegisterPOST /v1/webhooks
List allGET /v1/webhooks
DeleteDELETE /v1/webhooks/{id}
Send test eventPOST /v1/webhooks/test
See the API Reference → Webhooks 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.