budget_reached

Sent to the workspace webhook when this month's spend reaches 100% of the monthly budget. New calls and chats are blocked from then on.

budget_reached tells you the workspace has spent its monthly budget. From this point, requests to start new calls and chats are refused with budget_reached until the budget is raised or a new month starts.

When it fires#

On the budget check (about once a minute, and after billing settings are saved), the first time in a calendar month (UTC) that spend is at or above 100% of monthly_budget. At most once per month per workspace.

If budget_alert has not been sent yet this month, it is sent in the same check.

Which settings enable it#

A monthly_budget set on Billing or with PATCH /billing/settings.
The workspace webhook URL. No other URL is used.

Timeout: the workspace timeout, else 10 s. Retries: up to 3 (1 s, 2 s, 4 s).

Payload#

{
  "event": "budget_reached",
  "billing": {
    "month": "2026-10",
    "monthly_budget": 500,
    "month_usage": 500.0412,
    "percent": 100,
    "threshold": 100
  }
}

Fields#

Field	Type	Description
`billing.month`	string	Calendar month, `YYYY-MM`, UTC
`billing.monthly_budget`	number	The budget in AUD
`billing.month_usage`	number	Spend so far this month in AUD, 4 decimals
`billing.percent`	number	Percent of the budget, 1 decimal
`billing.threshold`	integer	`100` for this event

What happens next#

New calls and chats are refused with the code budget_reached and the message "Monthly budget of $500.00 reached. Raise the budget in Billing."
The Monthly budget card on Billing shows "Reached: new calls blocked".
Raising monthly_budget above current spend lifts the block. The event is not sent again in the same month, even if spend later reaches the new budget.

How to respond#

Reply 2xx. The body is ignored. Because this event blocks traffic, route it to someone who can raise the budget.