multi-router.aidocs

Budgets & Spend Control

WebhooksEnterprise

Sending budget alerts to your own systems, and verifying them.

A webhook endpoint is an https address where Multi-Router posts budget alerts, such as a chat channel's incoming webhook or an internal alerting service. Endpoints belong to an organization and are managed under Webhook endpoints in its Settings, and budget rules use them with the post to action.

Adding an endpoint

An endpoint is added in three steps:

  1. Open Settings, then Webhook endpoints, and select New endpoint.
  2. Enter a Name, such as Ops alerts, and the URL, such as https://hooks.example.com/mr.
  3. Select Create, and copy the signing secret, which is shown once.

The list shows each endpoint's URL, how many rules use it under Used by, and its last delivery. Rotate secret, then Generate and replace, replaces the secret, and the new one is shown once. An endpoint is deleted once no rule posts to it, and the post to action is offered once the organization has an endpoint.

Delivery

Multi-Router posts each alert as JSON over https with a verified certificate, and waits up to 10 seconds for a response. A timeout, a connection error or a 408, 425, 429 or 5xx response is retried, up to three attempts in all. Each alert has an id that stays the same across attempts, so the receiver can ignore a repeat.

Payload

Each alert is a JSON object with the alert's id, type, organization and details:

budget.threshold_reachedjson
{
  "id": "budget:bdg_4Rk8Vb2NwQ#monthly:2026-10@UTC#rule_1#rt_9Hk3Ws7PzQ#act_3f9c2a7e1b4d8065",
  "type": "budget.threshold_reached",
  "organization_id": "org_7Tq2Wd9KxP",
  "data": {
    "budget_id": "bdg_4Rk8Vb2NwQ",
    "budget_name": "Production API",
    "period": "monthly:2026-10@UTC",
    "rule_id": "rule_1",
    "action_index": 0,
    "subject": "rt_9Hk3Ws7PzQ",
    "watch": "per_router",
    "model": null,
    "spend_micros": 1620000000,
    "cap_micros": 2000000000,
    "threshold_micros": 1600000000,
    "threshold_ratio": 0.8,
    "remaining_micros": 380000000,
    "burn_rate_micros_per_min": 950000,
    "projected_cap_at": "2026-10-09T18:40:00Z",
    "period_resets_at": "2026-11-01T00:00:00Z",
    "label": "nearing"
  }
}

Amounts are in millionths of a US dollar, so 2000000000 is $2,000. subject is what crossed the line: the budget id for the total cap, the router id for router caps, and the model, or the router and model, for model caps. period names the period, such as daily:2026-10-09@UTC or lifetime@UTC. remaining_micros, projected_cap_at and period_resets_at can be null, and label is the budget's status.

Verifying the signature

Each delivery carries the header x-multi-router-signature-256 with sha256= and the hex HMAC-SHA256 of the raw body, keyed with the endpoint's signing secret. The receiver computes the same value and compares them:

Verify a deliverypython
import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Requests also carry Content-Type: application/json and User-Agent: multi-router-webhook/1.

Rules and AlertsOverrides and Requests
Was this helpful?