# Budget Alerts and Notifications

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[​](#prerequisites "Direct link to Prerequisites")

Before starting, prepare the following:

* At least one existing [budget](https://docs.api7.ai/ai-gateway/traffic-controls/budgets.md).
* A webhook URL or Slack incoming webhook URL for the organization notification channel.

## Configure Notification Channels[​](#configure-notification-channels "Direct link to 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. A webhook channel can also [customize the request body](#customize-the-request-body) and [add request headers](#add-request-headers).
* **Slack**: Set a [Slack incoming webhook](https://api.slack.com/messaging/webhooks) 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 for the rest of their 90-day retention; deliveries still queued for it are marked failed.

### Allow Private Network Destinations[​](#allow-private-network-destinations "Direct link to Allow Private Network Destinations")

An AISIX Enterprise control plane delivers to a channel whose URL resolves to a private, loopback, or link-local address by default, so a webhook receiver or Slack proxy on your intranet works without configuration.

To refuse such destinations, so that an operator-supplied URL cannot reach internal endpoints through the control plane, turn on SSRF protection with `AISIX_CLOUD_SSRF_PROTECTION_ENABLED=true` on the control plane API. The corresponding Helm chart value is `api.outbound.ssrfProtection.enabled`. You can still save a channel with a private URL, but test and alert deliveries to it fail unless its host is listed in the allowed hosts. The same setting governs the control plane's other outbound calls; see [Private Network Access](https://docs.api7.ai/ai-gateway/reference/on-premises-configuration.md#private-network-access).

## Configure Alert Thresholds[​](#configure-alert-thresholds "Direct link to 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-payload "Direct link to Webhook Payload")

By default, webhook channels receive the alert as this JSON document:

```
{

  "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",

  "currency": "USD"

}
```

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. Both the Slack message and `.message` below write amounts with the currency's symbol, `$` or `¥`.

The request `Content-Type` is always `application/json`.

### Customize the Request Body[​](#customize-the-request-body "Direct link to Customize the Request Body")

Set **Body template** on a webhook channel to send a body of your own shape instead of the default document. This is how you post alerts directly to a chat platform that expects its own message format. Leave the field empty to send the default document.

The template is a [Go `text/template`](https://pkg.go.dev/text/template). Write a variable as `{{ .name }}`. These names are available:

| Variable         | Description                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `.event`         | Event type, `budget_threshold`.                                                                                                               |
| `.dedup_key`     | Identifier shared by every delivery of one firing.                                                                                            |
| `.org_id`        | Organization ID.                                                                                                                              |
| `.budget_id`     | Budget ID.                                                                                                                                    |
| `.budget_name`   | Budget display name.                                                                                                                          |
| `.scope`         | Budget scope, such as `org`, `team`, or `member`.                                                                                             |
| `.scope_ref`     | ID of the scoped subject.                                                                                                                     |
| `.subject_name`  | Name of the scoped subject.                                                                                                                   |
| `.threshold_pct` | Threshold that fired, as a whole-number percentage.                                                                                           |
| `.percent`       | Spend as a percentage of the limit.                                                                                                           |
| `.spent_cents`   | Spend in the minor unit of `currency`: cents for USD, fen for CNY.                                                                            |
| `.limit_cents`   | Budget limit in the minor unit of `currency`.                                                                                                 |
| `.period`        | Budget period, such as `month`.                                                                                                               |
| `.period_start`  | Start of the current period, RFC 3339.                                                                                                        |
| `.triggered_at`  | Time the alert fired, RFC 3339.                                                                                                               |
| `.currency`      | The [organization's currency](https://docs.api7.ai/ai-gateway/cloud/organizations-and-environments.md#organization-currency), `USD` or `CNY`. |
| `.message`       | One-line human-readable summary of the alert.                                                                                                 |

The first sixteen are the fields of the default document; `.message` is an extra convenience, for example `Budget 'payments-team monthly' (team 'payments-team') reached 82.3% of its month limit: spent $82.30 of $100.00`.

One function is available: `json`, which renders a value as a JSON literal, quoting and escaping a string. Use it for every value you embed:

```
{"msg": {{ .message | json }}}
```

Interpolating inside quotes — `{"msg": "{{ .message }}"}` — also renders, but avoid it: a budget or team name the organization chose can contain a quote or a backslash, and the template then renders something that is not JSON. That fails the delivery permanently, and the alert is lost.

The following rules apply to a template:

* The rendered output must be valid JSON, and at most 64 KiB.
* Referencing a name outside the table is an error, not an empty string.
* `range`, `template`, and `block` are rejected. Every variable is a single string or number, so there is nothing to iterate over and no second template to invoke. `if` and `with` are available.
* The control plane renders the template against a sample alert when you save the channel, and rejects it if the result does not render or is not JSON.
* A template that renders at save time but fails on a real alert ends that delivery immediately — it is not retried.
* Unlike a header value, a template is **not** write-only: reads return it as written. Put credentials in [request headers](#add-request-headers), never in the template body.
* **Body template** and **Headers** are accepted on webhook channels only. Changing an existing webhook channel to `slack` while either is still set is rejected — clear them in the same request.

#### Chat Platform Examples[​](#chat-platform-examples "Direct link to Chat Platform Examples")

For a [Feishu (Lark) custom bot](https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot):

```
{"msg_type": "text", "content": {"text": {{ .message | json }}}}
```

For a [DingTalk custom robot](https://open.dingtalk.com/document/orgapp/custom-robot-access):

```
{"msgtype": "text", "text": {"content": {{ .message | json }}}}
```

For a [WeCom group robot](https://developer.work.weixin.qq.com/document/path/91770):

```
{"msgtype": "text", "text": {"content": {{ .message | json }}}}
```

To build the text yourself instead of using `.message`:

```
{"msgtype": "text", "text": {"content": {{ printf "Budget %s reached %d%% (%.1f%%) of its %s limit" .budget_name .threshold_pct .percent .period | json }}}}
```

### Add Request Headers[​](#add-request-headers "Direct link to Add Request Headers")

Set **Headers** on a webhook channel to send extra request headers with every delivery to it — a bearer token, a shared signing secret, or a tenant selector. This is the right place for a credential, because header values are write-only.

The following rules apply to headers:

* At most 16 headers.
* A name must be a valid HTTP header name of at most 128 characters. No two names may differ only in case.
* A value is at most 4096 characters and must not contain any control character — not only a line break.
* `Content-Type`, `Content-Length`, `Host`, `Transfer-Encoding`, and `Connection` are rejected, matched without regard to case. The control plane sets them itself.

Reading a channel returns the configured header names with every value replaced by `***`, so a read-modify-write round-trip works unchanged: submitting `***` for a name keeps the value already stored under it, matched without regard to case. Submitting `***` for a name that has nothing stored is rejected, since saving it would leave `***` as the header's value. Submitting an empty object removes every configured header.

## Verify Deliveries[​](#verify-deliveries "Direct link to Verify Deliveries")

The **Delivery log** in the **Notifications** view records the alerts the organization actually raised during the last 90 days. Delivery records older than 90 days are deleted automatically. 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 failure a retry cannot fix — a body template that does not render, for example — ends the delivery at once instead.

When a failed attempt received an HTTP response, the entry also carries that response's status code and body. The body is usually the only thing that explains a rejection the status code alone does not. It is kept as the destination sent it, up to 1 MiB, except that the credentials this channel sent — its URL, whole or as just the path and query, and any configured header value of at least 8 characters — are replaced by `***`, because destinations commonly echo them back in an error message. Shorter header values are left alone, since replacing them would redact unrelated text.

The delivery list carries the first 8 KiB of that body; select **Load full response** on an entry to fetch the rest from `GET /notification_deliveries/{delivery_id}`. Nothing is stored for a successful delivery, or for an attempt that never reached a response, such as a timeout, a refused address, or a name that does not resolve.

A test send does not appear in the delivery log. It is synchronous and is not retried; its result is returned to the dashboard directly, carrying the exact request body that was sent, plus the destination's status code and response body — masked the same way — whenever a response arrived, on success as well as on failure. Use it to confirm that a body template produces what you expect before relying on it.

note

When the deployment allows private destinations, which is the AISIX Enterprise default, a test send returns the destination's response body to anyone who can edit notification channels. On a control plane with untrusted operators, set `AISIX_CLOUD_SSRF_PROTECTION_ENABLED=true`.

## Manage Alerts with the AISIX Cloud Admin API[​](#manage-alerts-with-the-cloud-admin-api "Direct link to 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 Enterprise / Cloud Admin API](https://docs.api7.ai/ai-gateway/reference/cloud-admin-api.md) for request and response schemas.

## Next Steps[​](#next-steps "Direct link to Next Steps")

Continue with [Logging and Auditing](https://docs.api7.ai/ai-gateway/cloud/logging-and-auditing.md) to investigate the requests and control-plane changes behind budget behavior. To interpret the spend records that drive budget evaluation, see [Usage Reporting](https://docs.api7.ai/ai-gateway/cloud/usage-reporting.md#usage-and-budget-enforcement).
