Webhooks & Callbacks

Aithroyz sends deployment status events to your configured webhook endpoint as deployments progress through their lifecycle phases.

Webhook callbacks are sent from the Aithroyz provisioner for deployment events: started, progress updates, completed, and failed. Each callback is authenticated with HMAC-SHA256 using your webhook secret.

Callback payload

// POST to /api/requests/{id}/callback
// Authorization: Bearer <AITHROYZ_WEBHOOK_SECRET>
{
  "job_id": "job_abc123",
  "request_id": "req_xyz789",
  "status": "completed",   // started | progress | completed | failed
  "message": "All tools deployed and health checks passed",
  "outputs": {
    "elastic_url": "https://elastic.my-env.ops.aithroyz.com",
    "wazuh_url": "https://wazuh.my-env.ops.aithroyz.com",
    "elastic_password": "...",
    "wazuh_password": "..."
  },
  "timestamp": "2026-03-27T12:00:00Z"
}

Verifying callback authenticity

import hmac, hashlib

def verify_callback(body: bytes, auth_header: str, secret: str) -> bool:
    expected = f"Bearer {secret}"
    return hmac.compare_digest(auth_header, expected)

# In your webhook handler:
if not verify_callback(request.body, request.headers["Authorization"], WEBHOOK_SECRET):
    return 401

API KeysRead article →Lifecycle PhasesRead article →