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

Register a webhook endpoint URL with the event types you want to receive
AIOKA signs every delivery with an HMAC-SHA256 signature using your webhook secret
Your server verifies the signature and processes the payload
AIOKA retries failed deliveries up to 3 times with exponential backoff (5s → 25s → 125s)
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

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

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

Getting Started

Integrations

Webhooks

Webhooks

How It Works

Supported Events

Registering a Webhook

Verifying Signatures

Payload Format

`verdict.new`

`council.new`

`regime.change`

Limits

Managing Webhooks

Best Practices

​Webhooks

​How It Works

​Supported Events

​Registering a Webhook

​Verifying Signatures

​Payload Format

​verdict.new

​council.new

​regime.change

​Limits

​Managing Webhooks

​Best Practices

Webhooks

How It Works

Supported Events

Registering a Webhook

Verifying Signatures

Payload Format

`verdict.new`

`council.new`

`regime.change`

Limits

Managing Webhooks

Best Practices