Webhooks

Webhooks let CloudInfraOS push real-time event notifications to your own HTTP endpoints. Use them to integrate with Slack, Discord, CI/CD pipelines, or custom automation.

Webhook Endpoints

Webhook endpoints are configured per organization. Each endpoint subscribes to one or more event types and receives a POST request when those events occur.

Create a Webhook Endpoint

POST /api/webhooks

{
  "url": "https://hooks.example.com/stackpilot",
  "events": ["resource.created", "alert.triggered", "cost.threshold_exceeded"],
  "secret": "your_webhook_signing_secret"
}

Available Event Types

• resource.created — a new resource was discovered during sync
• resource.deleted — a previously synced resource no longer exists
• resource.updated — a resource configuration changed
• alert.triggered — an alert rule condition was met
• alert.resolved — a triggered alert returned to normal
• cost.threshold_exceeded — spend exceeded a configured threshold
• sync.completed — a provider sync finished
• sync.failed — a provider sync encountered an error

Webhook Delivery

Each webhook is delivered as an HTTP POST with a JSON body and an X-StackPilot-Signature header for payload verification. CloudInfraOS retries failed deliveries up to 3 times with exponential backoff.

Verifying Payloads

Use the signing secret to verify that incoming webhooks originated from CloudInfraOS. Compute an HMAC-SHA256 of the raw request body and compare it to the signature header:

const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Managing Endpoints

• GET /api/webhooks — list all webhook endpoints
• GET /api/webhooks/:id — get endpoint details and delivery history
• PATCH /api/webhooks/:id — update endpoint URL, events, or secret
• DELETE /api/webhooks/:id — delete an endpoint