Budget Alerts and Notifications

Budget alerts notify you when a budget's spend crosses a configured percentage of its limit — before a blocking budget starts rejecting traffic, or as the only signal on a warn-only budget. Alerts are delivered to the organization's notification channels: generic webhooks or Slack.

Budget alerts require an AISIX managed control plane, like budgets themselves.

Notification Channels

Notification channels are organization-level alert destinations, managed from the Notifications view. Every enabled channel receives every alert raised in the organization.

Two channel types are available:

• Webhook — the control plane sends each alert as a JSON POST to your URL. Use this to integrate with incident tooling, chat systems, or anything that accepts an HTTP callback.
• Slack — set a Slack incoming webhook URL and alerts arrive as a readable Slack message.

A channel's URL is write-only. After creation, every view shows only a masked form (https://hooks.slack.com/***) — for Slack incoming webhooks the URL path is the credential, so it is never echoed back. Editing a channel with the URL left empty keeps the stored URL.

Use the Test button to send a clearly labeled test notification through a channel and confirm the destination is reachable before relying on it.

Disabling a channel stops future deliveries to it. Deleting a channel keeps its past delivery records; deliveries still queued for it are marked failed.

Private Network Destinations

By default the control plane refuses channel URLs that resolve to private, loopback, or link-local addresses — on a shared control plane, an operator-supplied URL must not be able to reach internal endpoints. Self-hosted deployments whose webhook receiver or Slack proxy lives on an intranet can opt out by setting the AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS=true environment variable on the control plane API (Helm chart value api.notifyAllowPrivateURLs).

Alert Thresholds

Each budget carries a list of alert thresholds, expressed as percentages of its limit. The default is a single threshold at 80%. Configure them per budget in the Budgets view — for example 80, 100 to get an early warning and a limit-reached alert.

Thresholds above 100% are allowed and only ever fire on warn-only budgets: a blocking budget's spend cannot exceed its limit.

Each threshold fires once per budget period. When spend crosses 80% of a monthly budget, one alert goes to every enabled channel; further spend produces no repeat alerts until either the next threshold is crossed or the period rolls over and spend climbs back up. For a per-member team budget (each member in a team), each member alerts independently.

The control plane evaluates spend continuously — an alert is sent within roughly 30 seconds of usage crossing a threshold, even if no further traffic follows.

Webhook Payload

Webhook channels receive the alert as JSON:

{
  "event": "budget_threshold",
  "dedup_key": "budget_threshold:6f6d…:…:1782864000:80",
  "org_id": "1f0c…",
  "budget_id": "6f6d…",
  "budget_name": "payments-team monthly",
  "scope": "team",
  "scope_ref": "9a2b…",
  "subject_name": "payments-team",
  "threshold_pct": 80,
  "percent": 82.3,
  "spent_cents": 8230,
  "limit_cents": 10000,
  "period": "month",
  "period_start": "2026-07-01T00:00:00Z",
  "triggered_at": "2026-07-21T09:00:00Z"
}

Deliveries are at-least-once: a retried or multi-channel alert can reach the same receiver more than once. dedup_key is identical across all deliveries of one firing — use it to drop duplicates if your receiver must handle each alert only once. Slack channels receive the same information rendered as a text message.

Delivery Log and Retries

The Notifications view includes a delivery log — the audit trail of every outbound notification: its channel, status (pending, delivered, or failed), attempt count, the last error, and the exact payload sent.

Failed sends are retried automatically with increasing delays (1 minute after the first failure, then 5 minutes, 15 minutes, 1 hour, 6 hours). After six failed attempts the delivery is marked failed and stays in the log for inspection. A test send is synchronous and is not retried.

Managing Channels via API

Notification channels are part of the Cloud Admin API:

• GET /notification_channels
• POST /notification_channels
• GET /notification_channels/{channel_id}
• PATCH /notification_channels/{channel_id}
• DELETE /notification_channels/{channel_id}
• POST /notification_channels/{channel_id}/test

Budget alert thresholds are the alert_thresholds field on the budget resource. See the API reference for request shapes.