Webhooks

Overview

Webhooks are how CostOptix tells you something happened. Every alert in the product (budgets, daily limits, anomalies, runaway AI sessions, expiring credentials) goes out by webhook. Webhooks are available on every plan. Supported destinations:

Slack
Microsoft Teams (Workflow, recommended)
Microsoft Teams (legacy connector, deprecated by Microsoft)
Discord
Any HTTPS endpoint (custom)

Setting up a webhook

Go to Settings → Webhooks and click Add Webhook.
Pick the destination and paste its webhook URL.
Choose the events to subscribe to.
Optionally add a secret so you can verify deliveries.
Save, then click Test to send a test message.

Slack
Teams (Workflow)
Discord
Custom

Go to api.slack.com/apps and create an app.
Turn on Incoming Webhooks.
Click Add New Webhook to Workspace and pick a channel.
Copy the URL (https://hooks.slack.com/services/...).

Open the channel settings.
Go to Integrations → Webhooks → New Webhook.
Copy the URL (https://discord.com/api/webhooks/...).

Any HTTPS endpoint that accepts a POST with a JSON body. See Payload format.

Events

Event	Name in the app	Fires when
`budget.warning`	Budget Warning	A budget crosses its warning threshold
`budget.critical`	Budget Critical	A budget crosses its critical threshold
`budget.exceeded`	Budget Exceeded	A budget passes its limit for the period
`spend.daily_exceeded`	Daily Spend Limit Exceeded	A settled day’s spend passes a daily limit
`anomaly.detected`	Cost Anomaly Detected	An important anomaly is found
`llm.runaway_session`	Runaway AI Session	A coding-agent session spends far above your normal hourly rate
`unit_cost.changed`	Unit Cost Changed	A metric’s cost per unit jumped or went above its target (Professional and above). Revenue metrics never send it.
`credential.expiring`	Credential Expiring Soon	Cloud account credentials expire within 30 days
`credential.expired`	Credential Expired	Credentials expired and cost sync has stopped
`credential.rotated`	Credential Rotated	Cloud account credentials were rotated
`report.weekly`	Weekly Cost Report	Spend digest for the previous week (Professional and above)
`report.monthly`	Monthly Cost Report	Spend digest for the previous month (Professional and above)

Payload format

Slack, Teams and Discord get a formatted message. Custom endpoints get raw JSON, sent as POST with Content-Type: application/json. Every payload has the same envelope:

{
  "event": "budget.warning",
  "timestamp": "2026-10-01T14:32:00Z",
  "organization_id": "org_abc123",
  "data": { }
}

Budget (budget.warning, budget.critical, budget.exceeded)

"data": {
  "budget_id": "bud_xyz789",
  "budget_name": "Production AWS",
  "budget_amount": 5000.00,
  "current_spend": 4100.00,
  "predicted_spend": 5800.00,
  "utilization_percent": 82.0,
  "threshold": "warning",
  "account": "aws:123456789012",
  "period": "monthly",
  "days_remaining": 14,
  "breached_on": "2026-10-24",
  "excluded_currencies": []
}

breached_on is the projected breach date, or empty when none is projected. excluded_currencies lists plan currencies left out of an AI / LLM budget.

Unit cost (unit_cost.changed)

"data": {
  "metric_id": "5f0c2a9e-1b7d-4c1e-9a43-2d6b8e0f7a11",
  "metric_name": "Orders",
  "unit": "order",
  "scope": "org",
  "reason": "spike",
  "period": "2026-10-04",
  "unit_cost": 0.42,
  "expected": 0.31,
  "rise_percent": 35,
  "cost": 2100.00,
  "metric_value": 5000,
  "currency": "USD"
}

reason is spike when a daily cost per unit jumps above its recent history, with expected and rise_percent. It is above_target when a month passes the metric’s target, with target and final (whether the month’s costs have settled) instead. scope is org, team or selection. Team metrics add team_id and team_name.

Anomaly (anomaly.detected)

"data": {
  "account": "123456789012",
  "provider": "aws",
  "date": "2026-10-01",
  "service_name": "Amazon EC2",
  "amount": 340.50,
  "expected": 210.00,
  "impact": 130.50,
  "share_of_daily_spend": 0.06,
  "deviation_percent": 62.1,
  "type": "spike",
  "z_score": 4.2,
  "severity": "high",
  "top_resources": [
    {
      "resource_name": "i-0abc123",
      "resource_group": "",
      "anomaly_cost": 120.00,
      "baseline_cost": 15.00
    }
  ]
}

type is spike or stopped. top_resources is included when resource detail is available.

Daily limit (spend.daily_exceeded)

"data": {
  "source": "aws:123456789012",
  "source_label": "Production AWS",
  "date": "2026-10-01",
  "total": 812.40,
  "limit": 600.00,
  "top_services": []
}

Runaway AI session (llm.runaway_session)

"data": {
  "source": "claude_code",
  "session_id": "abc123",
  "user_key": "u_7f3a",
  "team_id": "payments",
  "repository": "checkout-service",
  "models": ["model-name"],
  "requests": 412,
  "value": 58.20,
  "threshold": 30.00,
  "baseline": 9.50,
  "multiple": 6.1,
  "window_min": 60,
  "first_at": "2026-10-01T09:02:11Z",
  "last_at": "2026-10-01T09:58:40Z"
}

user_key is a pseudonymous ID, never an email address.

Verifying deliveries

If you set a secret, every delivery carries an X-Webhook-Signature header: sha256= followed by the HMAC-SHA256 of the raw request body, using your secret as the key. Check it before trusting the payload:

const crypto = require('crypto');

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

Delivery and retries

Each delivery is tried up to 3 times, waiting longer between attempts.
A 4xx response is not retried, since it means the request itself was rejected.
Payloads are capped at 100 KB.
The last 50 deliveries for each webhook, with status codes and responses, are under History in Settings → Webhooks.

Getting Started

Connect Your Sources

See Your Spend

Act On It

Tools and Alerts

API Reference

Account

Security

Overview

Setting up a webhook

Events

Payload format

Verifying deliveries

Delivery and retries

​Overview

​Setting up a webhook

​Events

​Payload format

​Verifying deliveries

​Delivery and retries

Overview

Setting up a webhook

Events

Payload format

Verifying deliveries

Delivery and retries