Notification Channel Reference
Notification channels deliver organization alerts to webhooks or Slack. This page defines their payloads, customization rules, delivery behavior, and Admin API operations. For the operator workflow, see Budget Alerts and Notifications.
Channel Behavior
Every enabled channel receives every alert raised in its organization.
| Type | Behavior |
|---|---|
webhook | Sends a JSON POST to the configured URL. Supports a custom body template and request headers. |
slack | Sends a readable Slack message through an incoming webhook URL. Does not support a custom body or headers. |
Channel URLs are write-only. Reads return a masked value such as https://hooks.slack.com/***. When editing, leave the URL empty to retain the stored value.
Disabling a channel stops future deliveries until it is enabled again. Deleting a channel prevents future deliveries but retains its existing delivery records for the remainder of their 90-day retention period. Deliveries still queued for a deleted channel are marked failed.
AISIX Enterprise permits private, loopback, and link-local destinations by default. See Allow Private Network Destinations to change this behavior.
Webhook Payload
Without a body template, a webhook receives 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"
}
The request Content-Type is always application/json.
Deliveries are at-least-once. A retry or delivery to multiple channels can send the same alert more than once. Every delivery for one firing shares the same dedup_key; use it when the receiver must process the alert only once.
Slack channels contain the same information in a readable message. Monetary values in Slack and the .message template variable use the currency symbol, $ or ¥.
Customize the Request Body
Set Body template on a webhook channel to replace the default document. Leave it empty to use the standard payload.
The template uses Go text/template syntax. Write a value as {{ .name }}.

Template Variables
| Variable | Description |
|---|---|
.event | Event type, budget_threshold. |
.dedup_key | Identifier shared by every delivery for 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 or 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, in RFC 3339 format. |
.triggered_at | Time the alert fired, in RFC 3339 format. |
.currency | Organization currency, USD or CNY. |
.message | One-line summary of the alert. |
For example, .message can render as Budget 'payments-team monthly' (team 'payments-team') reached 82.3% of its month limit: spent $82.30 of $100.00.
Template Functions and Limits
Every Go text/template function is available, including printf, len, html, and urlquery. AISIX also provides json, which renders a value as a JSON literal. Use json for values embedded in a JSON body:
{"msg": {{ .message | json }}}
Do not interpolate a value inside quotes, such as {"msg": "{{ .message }}"}. A name containing a quote or backslash can otherwise produce invalid JSON and permanently fail the delivery.
The following limits apply:
- The rendered body must be valid JSON and at most 64 KiB.
- An unknown variable is an error rather than an empty value.
- Variable declarations,
if,else, andwithare available.range,template,define, andblockare rejected. - Function output counts toward a 64 KiB render budget. A
printfwidth or precision counts at its maximum possible output before the function runs. - AISIX validates the template with a sample alert when the channel is saved. A refused template, render error, or non-JSON result returns
400. - A template that fails on a real alert ends that delivery without a retry.
- A template saved before an upgrade remains stored if newer rules reject it, but each delivery fails until the template is corrected. AISIX Enterprise logs a startup warning for affected channels.
- Body templates are returned as written. Never put credentials in a template; use request headers instead.
Chat Platform Examples
Feishu or Lark custom bot:
{"msg_type": "text", "content": {"text": {{ .message | json }}}}
DingTalk custom robot:
{"msgtype": "text", "text": {"content": {{ .message | json }}}}
WeCom group robot:
{"msgtype": "text", "text": {"content": {{ .message | json }}}}
Add Request Headers
Webhook channels can send additional headers, such as a bearer token, signing secret, or tenant selector. Header values are write-only.
The following limits apply:
- A channel can define at most 16 headers.
- A name must be a valid HTTP header name of at most 128 characters. Names are unique without regard to case.
- A value can contain at most 4096 characters and no control characters.
Content-Type,Content-Length,Host,Transfer-Encoding, andConnectionare reserved and rejected without regard to case.
Reads return each header name with its value replaced by ***. Sending *** back for an existing name retains the stored value. The control plane rejects *** for a new name. Send an empty object to remove all configured headers.
Custom bodies and headers are supported only on webhook channels. Clear both in the same request before changing a webhook channel to slack.
Delivery Behavior
The Delivery log retains events for 90 days and records the channel, status, attempt count, last error, and exact payload.
Failed sends use this retry schedule:
| Failed attempt | Delay before the next attempt |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 15 minutes |
| 4 | 1 hour |
| 5 | 6 hours |
After six failed attempts, the delivery becomes Failed. A permanent error, such as a body template that cannot render, fails immediately without retries.
When an HTTP destination rejects an attempt, AISIX stores its status code and up to 1 MiB of its response body. Before storage, AISIX replaces the channel URL, its path and query, and configured header values of at least eight characters with ***. Shorter values remain because replacing them would redact unrelated text.
The delivery list initially returns the first 8 KiB of a stored response. Select Load full response to retrieve the remainder from GET /notification_deliveries/{delivery_id}. Successful attempts and failures that receive no HTTP response, such as a timeout or DNS failure, store no response body.
Test sends run synchronously without retries and do not appear in the delivery log. Their result contains the rendered request body and, when the destination responds, its status code and masked response body.
When private destinations are allowed, a test send returns the destination response to anyone who can edit notification channels. Enable SSRF protection on a control plane with untrusted operators.
Notification Channel Operations
The AISIX Enterprise / Cloud Admin API provides these operations:
GET /notification_channelsPOST /notification_channelsGET /notification_channels/{channel_id}PATCH /notification_channels/{channel_id}DELETE /notification_channels/{channel_id}POST /notification_channels/{channel_id}/testGET /notification_deliveriesGET /notification_deliveries/{delivery_id}
Budget alert thresholds are the alert_thresholds field on a budget. See the AISIX Enterprise / Cloud Admin API for schemas and error responses.