> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requesty.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Spending Alerts
> Monitor spending across your organization with configurable alert thresholds and webhook notifications
Requesty's spending alerts let you monitor costs across your organization in real time. Define threshold rules for users, groups, or the organization as a whole, and receive instant notifications via webhook whenever a threshold is crossed.
**[Set up alerts](https://app.requesty.ai/admin-panel/alerts)** in the Requesty Console.
## How Alerts Work
Every time a request is processed, Requesty evaluates the updated spend against your configured alert thresholds. When a threshold is crossed for the first time, a notification is dispatched to your webhook endpoint. Alerts fire exactly once per threshold crossing, they will not repeat until the threshold is crossed again (e.g. in a new billing cycle).
```mermaid theme={"dark"}
graph LR
A[API Request] --> B[Balance Updated]
B --> C{Threshold Crossed?}
C -- Yes --> D[Send Webhook]
C -- No --> E[No Action]
```
## Alert Types
Requesty supports six types of spending alerts, each designed for a different monitoring scenario:
Triggers when a user's monthly spend reaches a percentage of their configured budget. Applies to both global user budgets and group-based user budgets.
Triggers when a user's monthly spend reaches a specific dollar amount. Applies to both global user spend and group-based user spend. Works even if no budget limit is set.
Triggers when a group's combined monthly spend reaches a percentage of the group's budget.
Triggers when the organization's remaining balance drops below a specific dollar amount, useful for ensuring you top up before running out of credits.
Triggers when an API key's monthly spend reaches a percentage of its configured monthly budget. Requires a monthly spend limit to be set on the API key.
Triggers when an API key's monthly spend reaches a specific dollar amount. Works even if no budget limit is set on the key.
### Alert Type Examples
| Alert Type | Threshold Unit | Example | When It Fires |
| ---------------------- | ------------------- | ------- | ----------------------------------------------------------- |
| User % of Budget | Percentage (0-100%) | 80% | User has spent 80% of their monthly limit |
| User Absolute Spend | Dollar amount | \$50 | User has spent \$50 this month (globally or within a group) |
| Group % of Budget | Percentage (0-100%) | 90% | Group has spent 90% of its monthly limit |
| Org Balance Below | Dollar amount | \$100 | Organization balance drops below \$100 |
| API Key % of Budget | Percentage (0-100%) | 80% | API key has spent 80% of its monthly limit |
| API Key Absolute Spend | Dollar amount | \$25 | API key has spent \$25 this month |
You can create multiple thresholds per alert type. For example, set User % of Budget alerts at both 50% and 80% to get an early warning and a critical warning.
## Setting Up Alerts
### Step 1: Configure a Webhook
Before alerts can be delivered, you need to configure a webhook endpoint for your organization.
1. Go to the [Admin Panel](https://app.requesty.ai/admin-panel) and navigate to the **Alerts** tab
2. Click **Add Webhook** in the header
3. Choose a webhook type:
* **JSON (Generic)**, sends a structured JSON payload to any HTTP endpoint
* **Slack**, sends a pre-formatted message to a Slack incoming webhook URL
* **Teams**, sends a Microsoft Adaptive Card to a Teams incoming webhook URL
4. Enter your webhook URL
5. Click **Save**
Alerts will not be sent unless a valid webhook URL is configured. If you create alert thresholds without a webhook, they will be stored but no notifications will be delivered.
### Step 2: Create Alert Thresholds
1. In the Alerts tab, click **Add Alert**
2. Select an alert type from the dropdown
3. Enter the threshold value:
* For percentage-based alerts, enter a number between 1 and 100
* For dollar-based alerts, enter the dollar amount
4. Click **Create Alert**
You can create as many thresholds as needed across all alert types.
## Webhook Payload Formats
### JSON Webhook
When the webhook type is set to **JSON**, alerts are delivered as a structured JSON payload via HTTP POST:
```json User % of Budget theme={"dark"}
{
"type": "user.budget.exceeded_percent",
"data": {
"user_id": "user_abc123",
"user_email": "alice@company.com",
"limit": "100",
"percentage_exceeded": "0.8"
}
}
```
```json User % of Budget (in Group) theme={"dark"}
{
"type": "user.budget.exceeded_percent",
"data": {
"user_id": "user_abc123",
"user_email": "alice@company.com",
"group_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"group_name": "Engineering",
"limit": "50",
"percentage_exceeded": "0.8"
}
}
```
```json User Absolute Spend theme={"dark"}
{
"type": "user.budget.exceeded_absolute",
"data": {
"user_id": "user_abc123",
"user_email": "alice@company.com",
"absolute_exceeded": "50"
}
}
```
```json User Absolute Spend (in Group) theme={"dark"}
{
"type": "user.budget.exceeded_absolute",
"data": {
"user_id": "user_abc123",
"user_email": "alice@company.com",
"group_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"group_name": "Engineering",
"absolute_exceeded": "50"
}
}
```
```json Group % of Budget theme={"dark"}
{
"type": "group.budget.exceeded_percent",
"data": {
"group_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"group_name": "Engineering",
"group_admins": [
{ "email": "admin@company.com" }
],
"limit": "500",
"percentage_exceeded": "0.9"
}
}
```
```json Org Balance Below theme={"dark"}
{
"type": "org.balance.below_absolute",
"data": {
"org_id": "org_abc123",
"balance_threshold": "100",
"current_balance": "87.50"
}
}
```
```json API Key % of Budget theme={"dark"}
{
"type": "apikey.budget.exceeded_percent",
"data": {
"api_key_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"api_key_name": "production-key",
"limit": "100",
"percentage_exceeded": "0.8"
}
}
```
```json API Key Absolute Spend theme={"dark"}
{
"type": "apikey.budget.exceeded_absolute",
"data": {
"api_key_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"api_key_name": "production-key",
"absolute_exceeded": "50"
}
}
```
### Slack Webhook
When the webhook type is set to **Slack**, alerts are delivered as Slack-formatted messages. Each alert type produces a human-readable notification:
* **User % of budget alerts**: *"User Spend Threshold Exceeded, [alice@company.com](mailto:alice@company.com) (user\_abc123) exceeded 80% of their \$100 monthly limit"* (includes group name and ID when triggered within a group)
* **User absolute spend alerts**: *"User Spend Threshold Exceeded, [alice@company.com](mailto:alice@company.com) (user\_abc123) exceeded \$50 spend threshold"* (includes group name and ID when triggered within a group)
* **Group alerts**: *"Group Spend Threshold Exceeded. Engineering (d290f1ee-6c54-4b01-90e6-d701748f0851) exceeded 90% of the \$500 monthly limit"* (includes group admin emails)
* **Org alerts**: *"Organization Balance Alert. Organization balance has dropped below \$100 threshold. Current balance: 87.50"*
* **API key % of budget alerts**: *"API Key Spend Threshold Exceeded. API key production-key (d290f1ee-6c54-4b01-90e6-d701748f0851) exceeded 80% of the \$100 monthly limit"*
* **API key absolute spend alerts**: *"API Key Spend Threshold Exceeded. API key production-key (d290f1ee-6c54-4b01-90e6-d701748f0851) exceeded \$50 spend threshold"*
### Teams Webhook
When the webhook type is set to **Teams**, alerts are delivered as [Adaptive Card](https://adaptivecards.io/) messages via HTTP POST. Each alert is rendered as a card with a bold title and a descriptive body inside Microsoft Teams.
The payload follows the Teams incoming webhook Adaptive Card format:
```json Example Adaptive Card Payload theme={"dark"}
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.4",
"body": [
{
"type": "TextBlock",
"text": "⚠ User Spend Threshold Exceeded",
"weight": "Bolder",
"size": "Medium"
},
{
"type": "TextBlock",
"text": "**alice@company.com** (user_abc123) exceeded **80%** of their **$100** monthly limit in group **Engineering** (d290f1ee-6c54-4b01-90e6-d701748f0851)",
"wrap": true
}
]
}
}
]
}
```
Each alert type produces the following card titles and body text:
| Alert Type | Title | Body |
| ---------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User % of budget | ⚠ User Spend Threshold Exceeded | **[alice@company.com](mailto:alice@company.com)** (user\_id) exceeded **80%** of their **\$100** monthly limit (includes group name and ID when triggered within a group) |
| User absolute spend | ⚠ User Spend Threshold Exceeded | **[alice@company.com](mailto:alice@company.com)** (user\_id) exceeded **\$50** spend threshold (includes group name and ID when triggered within a group) |
| Group | ⚠ Group Spend Threshold Exceeded | **Engineering** (group\_id) exceeded **90%** of the **\$500** monthly limit (includes group admin emails) |
| Org | ⚠ Organization Balance Alert | Organization balance has dropped below **$100** threshold. Current balance: **$87.50** |
| API key % of budget | ⚠ API Key Spend Threshold Exceeded | API key **production-key** (api\_key\_id) exceeded **80%** of the **\$100** monthly limit |
| API key absolute spend | ⚠ API Key Spend Threshold Exceeded | API key **production-key** (api\_key\_id) exceeded **\$50** spend threshold |
To set up a Teams incoming webhook, create one via the **Workflows** app in Microsoft Teams (or the legacy "Incoming Webhook" connector). Copy the generated URL and paste it into the Requesty webhook configuration.
## Webhook Delivery
Requesty's webhook dispatcher ensures reliable delivery:
* **Retries**: Failed deliveries are retried up to **3 times** with exponential backoff
* **Timeout**: Each delivery attempt times out after **15 seconds**
## Managing Alerts
### Viewing Active Alerts
All configured alert thresholds are visible in the **Alerts** tab of the [Admin Panel](https://app.requesty.ai/admin-panel). The table shows:
* Alert type and description
* Threshold value
* Status (active)
### Deleting Alerts
To remove an alert threshold, click the delete icon next to the alert in the table and confirm the deletion.
### Updating the Webhook
Click **Edit** next to the webhook display in the Alerts header to change the webhook type or URL. Updating the webhook takes effect immediately for all future alert notifications.
## Example Configurations
* **Org Balance Below \$50**, get notified before credits run out
* **User Absolute Spend \$20**, catch unexpectedly high individual usage
* **Webhook**: Slack channel `#billing-alerts`
* **User % of Budget at 50%, 80%, 95%**, progressive warnings as users approach limits
* **Group % of Budget at 80%, 95%**, monitor departmental spend
* **Org Balance Below $500, $200**, early and critical low-balance warnings
* **User Absolute Spend $100, $500**, catch runaway usage regardless of budget
* **Webhook**: JSON endpoint integrated with internal alerting system (e.g., PagerDuty, Opsgenie)
* **API Key % of Budget at 50%, 80%, 95%**, progressive warnings as keys approach their limits
* **API Key Absolute Spend $25, $50**, track per-key usage by dollar amount
* **Org Balance Below \$100**, ensure account stays funded
* **Webhook**: JSON endpoint for automated processing
## Related Features
Set hard spending caps at the user, project, or API key level to enforce budgets automatically.
Organize users into groups with shared budgets and collective spending tracking.
View detailed spending breakdowns and usage trends across your organization.
Monitor real-time costs per request, model, and user.