Docs / API & Webhooks / Webhook Endpoints and Event Flow

Webhook Endpoints and Event Flow

Published · Last updated: May 2026 · 3 min read

Who this is for

Developers building integrations that need to react to CloudAIPilot events (deployment completed, backup failed, alert fired, etc.) in real time.

What you will complete

Understand how outbound webhooks work, what events are available, the payload format, and how to verify payload authenticity.

Before you begin

  • A publicly accessible HTTPS endpoint that can receive POST requests.
  • Admin or Owner role to configure notification channels.

How outbound webhooks work

CloudAIPilot sends an HTTP POST request to your configured webhook URL whenever a subscribed event occurs. Your endpoint receives a JSON payload describing the event, processes it, and responds with HTTP 200 OK.

Event flow:

  1. An event occurs in CloudAIPilot (alert fires, deployment completes, backup fails, etc.)
  2. CloudAIPilot sends a POST request to all active webhook channels
  3. Your endpoint receives and processes the payload
  4. You respond with 200 OK within 10 seconds
  5. CloudAIPilot logs the delivery in the notification history

Configuring a webhook channel

  1. Go to Settings → Notification Channels → Add Channel.
  2. Select Webhook.
  3. Enter a channel name and your endpoint URL (must be HTTPS).
  4. Optionally enter a Secret for HMAC-SHA256 payload signing.
  5. Click Add Channel, then Test to verify your endpoint receives the test payload.

Payload structure

Every webhook payload is a JSON object with this structure:

{
  "event": "alert.fired",
  "timestamp": "2026-05-30T14:22:00Z",
  "organization_id": "org_abc123",
  "data": {
    "server_name": "web-server-01",
    "metric": "cpu",
    "value": 96.2,
    "severity": "critical",
    "alert_rule": "CPU Usage > 95%"
  }
}

The event field identifies the event type. The data object contains event-specific details.

Available event types

Events are grouped by category:

Servers: server.provisioned, server.provision_failed, server.agent_installed, server.externally_deleted, server.ssh_setup_complete, server.ssh_setup_failed, ssl.expiring, ssl.renewed

Backups: backup.completed, backup.failed, restore.completed, restore.failed

Deployments: deploy.success, deploy.failed, deploy.rolled_back, app.deploy_succeeded, app.deploy_failed

FinOps & Alerts: alert.fired, alert.resolved, finops.anomaly.detected, finops.budget.exceeded, finops.waste.detected, finops.recommendation.created, finops.report.delivered

Security: security.new_login, security.failed_logins

Team: team.member_invited, team.role_changed

Goals & Insights: goal.completed, goal.failed, goal.blocked

Verifying payload authenticity (HMAC-SHA256)

If you configured a secret when creating the webhook channel, CloudAIPilot signs every payload with HMAC-SHA256. The signature appears in the request header:

X-CloudAIPilot-Signature: sha256=HEXDIGEST

To verify the signature on your server:

import hmac, hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    received = signature_header.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

Always verify the signature before processing the payload in production. Reject any request that fails verification.

Retry behavior

If your endpoint returns a non-200 response or times out (over 10 seconds), CloudAIPilot retries the delivery:

  • Retry 1: 30 seconds after the first failure
  • Retry 2: 5 minutes after retry 1
  • After 3 total attempts: delivery is marked as failed in the notification history

To avoid retry issues, respond with 200 OK as quickly as possible. Process the payload asynchronously if the processing takes more than a few seconds.

Related articles