fix(proxy): deliver budget alerts on webhook-only alerting and accept ALERTING_WEBHOOK_URL

[devin-ai-integration]

TLDR

Problem this solves:

• alerting: ["webhook"] silently never delivered budget alerts
• webhook URL for Slack-format alerts could only be named SLACK_WEBHOOK_URL
• air-gapped users on Rocket.Chat/Mattermost need non-Slack, non-email alerting

How it solves it:

• forward budget alerts when webhook is in alerting, not only slack
• accept ALERTING_WEBHOOK_URL as a provider-neutral env fallback
• mark the new var sensitive; de-brand admin UI alerting copy

User Flow

Before: an admin who configured webhook-only budget alerts gets nothing at their receiver

1. They set general_settings.alerting: ["webhook"] and WEBHOOK_URL=https://chat.internal/hooks/abc, then start the proxy
2. They send GET http://localhost:4000/health/services?service=webhook with the master key
3. The response is 200 null, but their webhook receiver never gets a request and no error is logged
4. Real budget-crossed events are dropped the same way, so budgets are exceeded with no alert

After: the same config delivers the structured budget alert to their webhook

1. They set general_settings.alerting: ["webhook"] and WEBHOOK_URL=https://chat.internal/hooks/abc, then start the proxy
2. They send GET http://localhost:4000/health/services?service=webhook with the master key
3. The response is 200 and the receiver gets the JSON budget event ("event":"budget_crossed", spend, budget, key/team identifiers)
4. Additionally, for Slack-format alerts to a Slack-compatible receiver (Rocket.Chat, Mattermost), they can set ALERTING_WEBHOOK_URL instead of SLACK_WEBHOOK_URL; alerting: ["slack"] then posts the {"text": ...} payload there

Relevant issues

Linear ticket

Resolves LIT-6235

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Shared setup: a local HTTP receiver on port 9999 logs every POST it gets (path + body). Proxy config is minimal: master_key: sk-1234 plus the alerting list named per case. The health endpoints below call the exact same budget-alert path real traffic uses. All requests are byte-identical across Before and After

Before (77765fd)

webhook-only budget alert is silently dropped

1. Start the proxy with alerting: ["webhook"] and WEBHOOK_URL=http://localhost:9999/generic-hook
2. curl -s -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer sk-1234" "http://localhost:4000/health/services?service=webhook"
3. Output: null / HTTP 200, and the receiver log stays empty: the alert never arrives and nothing is logged

control: same request with "slack" also enabled does deliver

1. Start the proxy with alerting: ["slack", "webhook"], same WEBHOOK_URL, SLACK_WEBHOOK_URL=http://localhost:9999/slack-format
2. Same curl as above
3. Receiver log now shows the structured event, proving the fixture works and the gate is the cause:

{"path": "/generic-hook", "body": "{\"spend\":1.0,\"max_budget\":0.0,...,\"event\":\"budget_crossed\",\"event_message\":\"User Budget: Budget Crossed\\n Total Budget:`0.0`\"}"}

neutral env var name is rejected

1. Start the proxy with alerting: ["slack"] and only ALERTING_WEBHOOK_URL=http://localhost:9999/neutral-hook set
2. curl -s -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer sk-1234" "http://localhost:4000/health/services?service=slack"
3. Output: HTTP 500 with Missing SLACK_WEBHOOK_URL from environment; receiver log stays empty

After (5c4529e)

webhook-only budget alert is silently dropped

1. Start the proxy with alerting: ["webhook"] and WEBHOOK_URL=http://localhost:9999/generic-hook
2. Same curl: curl -s -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer sk-1234" "http://localhost:4000/health/services?service=webhook"
3. Receiver log now shows the structured budget event:

{"path": "/generic-hook", "body": "{\"spend\":1.0,\"max_budget\":0.0,\"soft_budget\":null,\"token\":\"litellm_proxy_master_key\",\"customer_id\":null,\"user_id\":\"default_user_id\",\"team_id\":null,\"team_alias\":null,\"organization_id\":null,\"user_email\":null,\"key_alias\":null,\"projected_exceeded_date\":null,\"projected_spend\":null,\"event_group\":\"key\",\"alert_emails\":null,\"max_budget_alert_emails\":null,\"event\":\"budget_crossed\",\"event_message\":\"User Budget: Budget Crossed\\n Total Budget:`0.0`\"}"}

control: same request with "slack" also enabled does deliver

1. Unchanged; both channels still deliver as before

neutral env var name is rejected

1. Start the proxy with alerting: ["slack"] and only ALERTING_WEBHOOK_URL=http://localhost:9999/neutral-hook set
2. Same curl to /health/services?service=slack
3. Output: HTTP 200 {"status":"success",...} and the Slack-format alert arrives at the neutral URL:

{"path": "/neutral-hook", "body": "{\"text\": \"Alert type: `budget_alerts`\\nLevel: `Low`\\nTimestamp: `01:35:08`\\n\\nMessage: This is a test slack alert message\"}"}

Type

🐛 Bug Fix

Caveats (if any)

Medium

• structured-JSON WEBHOOK_URL channel remains env-only, no UI surface
• UI alerting toggle still overwrites alerting with ["slack"]/[]

Low

• SLACK_WEBHOOK_URL wins over ALERTING_WEBHOOK_URL when both set
• shipped dashboard bundle picks up new copy on next UI build
• the documentation CI job stays red until docs(proxy): document ALERTING_WEBHOOK_URL env var litellm-docs#1038 (documents ALERTING_WEBHOOK_URL) merges; verified green locally against that docs branch

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/0a30e0282ed54b3e8687cd9546a61faf
Requested by: @yassin-berriai

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[devin-ai-integration]

No action taken on #38441 — author matches devin-ai-integration[bot] but the PR has no enterprise label, so it's out of scope. No risk label applied, no Linear routing.

[devin-ai-integration]

@greptileai

[greptile-apps]

Greptile Summary

The PR enables structured budget-alert delivery for webhook-only configurations, adds ALERTING_WEBHOOK_URL as a provider-neutral fallback for Slack-compatible alerting, protects the new variable as sensitive, and updates dashboard copy.

• Routes budget alerts when either slack or webhook alerting is enabled.
• Applies the neutral webhook fallback consistently to immediate and digest Slack-format alerts.
• Adds regression coverage for webhook-only forwarding, URL fallback precedence, and missing configuration.
• Synchronizes the generated dashboard API declaration with the updated alerting schema description.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the only commit after the prior assessment synchronizes the generated dashboard API declaration with its source schema description.

Important Files Changed

Filename	Overview
ui/litellm-dashboard/src/lib/http/schema.d.ts	The only change since the prior 5/5 review updates one generated description line to exactly match the current OpenAPI schema source.
litellm/proxy/utils.py	The budget-alert gate now forwards webhook-only configurations into the existing structured webhook delivery path.
litellm/integrations/SlackAlerting/slack_alerting.py	Immediate and digest Slack-format alerts consistently prefer SLACK_WEBHOOK_URL and fall back to ALERTING_WEBHOOK_URL.
litellm/proxy/proxy_server.py	ALERTING_WEBHOOK_URL is included in both relevant sensitive-variable registries.
litellm/proxy/_types.py	The alerting schema description documents the supported channels and payload formats and is synchronized with the generated declaration.

_{Reviews (4): Last reviewed commit: "chore(ui): regenerate schema.d.ts for up..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...tellm/integrations/SlackAlerting/slack_alerting.py	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[devin-ai-integration]

@greptileai

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_webhook_budget_alerts (00c0fba) with litellm_internal_staging (df848d8)}

[devin-ai-integration]

Greptile Confidence Score 5/5 (comment 5433175998) was judged at c524cf9. The only commit after it, 5c4529e, changes a single generated line in ui/litellm-dashboard/src/lib/http/schema.d.ts (npm run gen:api output for the updated alerting description) — no hand-written code changed. A re-review was requested at 01:36 UTC via @greptileai but has not posted.