Skip to main content
API7.ai Logo

Budget Alerts and Notifications

AISIX Cloud budget alerts notify you when spend crosses a configured percentage of a budget limit. Use them to warn operators before a blocking budget starts rejecting traffic or to monitor a warn-only budget.

Prerequisites​

Before starting, prepare the following:

  • At least one existing budget.
  • A webhook URL or Slack incoming webhook URL for the organization notification channel.

Configure 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 other systems that accept HTTP callbacks.
  • Slack: Set a Slack incoming webhook URL to receive alerts as readable Slack messages.

Create and test a channel:

  1. Open Notifications, then select New channel.
  2. Enter a Name, select the channel Type, and enter its URL.
  3. Keep Enabled selected, then select Create channel.
  4. Select Test for the new channel and confirm that the destination receives the test notification.

A channel's URL is write-only. After creation, the control plane shows only a masked form such as https://hooks.slack.com/***. Editing a channel with the URL left empty keeps the stored URL.

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

Allow Private Network Destinations​

You can save a channel whose URL resolves to a private, loopback, or link-local address, but test and alert deliveries to that URL fail by default. This prevents an operator-supplied URL on a shared control plane from reaching internal endpoints.

For an on-premises control plane whose webhook receiver or Slack proxy is on an intranet, set AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS=true on the control plane API. The corresponding Helm chart value is api.notifyAllowPrivateURLs.

Configure Alert Thresholds​

Each budget carries a list of alert thresholds, expressed as percentages of its limit. Configure thresholds for each budget:

  1. Open the Budgets view and select the budget to edit.
  2. In Alert thresholds (%), enter one or more whole-number percentages separated by commas. For example, use 80, 100 to receive an early warning and a limit-reached alert.
  3. Save the budget.

You can enter up to 20 unique thresholds from 1 through 200. If you leave the field empty, the control plane uses 80.

Each threshold fires once per budget period. When spend crosses 80% of a monthly budget, the control plane sends one alert to every enabled channel. It does not repeat the 80% alert during the same period, but another configured threshold can trigger its own alert. After the period resets, each threshold can fire again. For a per-member team budget (each member in a team), each member alerts independently.

For a blocking budget, thresholds above 100% are normally not reached because later requests are rejected at the limit. However, a request admitted below the limit can complete above it, and concurrent requests can also produce an overshoot. A threshold above 100% can fire when this occurs.

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.

Verify Deliveries​

The Delivery log in the Notifications view records every outbound notification. Each entry includes its channel, status (pending, delivered, or failed), attempt count, last error, and exact payload.

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 remains in the log for inspection. A test send is synchronous and is not retried.

Manage Alerts with the AISIX Cloud Admin API​

Notification channels are part of the AISIX 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 AISIX Cloud Admin API Reference for request and response schemas.

Next Steps​

Continue with Logging and Auditing to investigate the requests and control-plane changes behind budget behavior. To interpret the spend records that drive budget evaluation, see Usage Reporting.