Platform
Webhooks
We send an HTTPS POST to your endpoint when something happens in your organization: a spend threshold, low balance, a finished batch, a BYO status change, a suspended key.
Setting up an endpoint
Add endpoints on the dashboard's Webhooks page. For each one, choose the events it receives. When you add it, you get a signing secret that starts with whsec_. It is shown once.
Endpoint URLs must be public https:// addresses. You can send a test event to an endpoint from the dashboard; its data is {"message": "Test event from Utmost."}.
Payload
Every delivery has the same envelope:
{
"type": "batch.completed",
"timestamp": "2026-11-19T05:42:27.000Z",
"data": { ... }
}timestamp is when the event happened, in ISO 8601 UTC.
Events
spend.threshold
A key or project crossed 50% or 80% of its monthly spend cap.
{ "type": "spend.threshold", "timestamp": "...", "data": { "scope": "key", "id": "key_NUZl7evjxRIH60U0kR9a", "percent": 80, "spent_usd": 40.12, "cap_usd": 50, "period": "2026-11" } }scope is key or project; id is the key or project id.
spend.cap_reached
Same fields, with percent: 100. Requests on that key or project now fail with spend_cap_reached.
{ "type": "spend.cap_reached", "timestamp": "...", "data": { "scope": "project", "id": "prj_Y9aTKhJIrBpYi8ueVw1f", "percent": 100, "spent_usd": 500.03, "cap_usd": 500, "period": "2026-11" } }credits.low
The balance fell below your low-balance threshold. Sent at most once a day.
{ "type": "credits.low", "timestamp": "...", "data": { "balance_usd": 4.87 } }credits.added
A top-up was credited.
{ "type": "credits.added", "timestamp": "...", "data": { "amount_usd": 100, "payment_id": "pay_..." } }usage.daily
Yesterday's usage (UTC day), by served model. Sent once a day.
{
"type": "usage.daily",
"timestamp": "...",
"data": {
"date": "2026-11-18",
"total_cost_usd": 12.53,
"models": [
{ "model": "utmost/kimi-k3.1-pro", "requests": 310, "input_tokens": 1820044, "cached_tokens": 902113, "output_tokens": 410220, "cost_usd": 9.71 },
{ "model": "utmost/qwen3-30b-a3b", "requests": 5021, "input_tokens": 3110342, "cached_tokens": 120988, "output_tokens": 990876, "cost_usd": 2.82 }
]
}
}Requests that failed before a model was chosen are grouped under "model": "none".
batch.completed
A batch finished.
{ "type": "batch.completed", "timestamp": "...", "data": { "batch_id": "batch_6HsowVhheD3l7E8JGI4V", "status": "completed", "completed": 1998, "failed": 2, "total": 2000, "cost_usd": 3.41 } }status is completed, cancelled or expired.
byo.status_changed
A bring-your-own-model job changed status.
{ "type": "byo.status_changed", "timestamp": "...", "data": { "job_id": "byo_Fq2...", "name": "qwen3-8b-redteam", "status": "awaiting_approval", "detail": "Eval finished. Review the report, then approve or reject." } }key.suspended
A key was suspended after a request hit the child-safety hard limit. See Safety.
{ "type": "key.suspended", "timestamp": "...", "data": { "key_id": "key_NUZl7evjxRIH60U0kR9a", "key_prefix": "ut_live_a1b2c3", "reason": "hard_limit" } }Verifying signatures
Deliveries are signed with the Standard Webhooks scheme (HMAC-SHA256). Each request has three headers:
| Header | Value |
|---|---|
webhook-id |
The delivery id, e.g. msg_.... The same on every retry. |
webhook-timestamp |
Unix seconds when this attempt was signed |
webhook-signature |
v1,<base64 signature> |
The signed content is <webhook-id>.<webhook-timestamp>.<raw body>. Verify against the raw request body, before any JSON parsing. The libraries below also reject timestamps more than 5 minutes from now, which protects against replays.
TypeScript
npm install standardwebhooksimport { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.UTMOST_WEBHOOK_SECRET!); // "whsec_..."
// Next.js route handler
export async function POST(req: Request) {
const body = await req.text();
let event: { type: string; timestamp: string; data: Record<string, unknown> };
try {
event = wh.verify(body, {
"webhook-id": req.headers.get("webhook-id") ?? "",
"webhook-timestamp": req.headers.get("webhook-timestamp") ?? "",
"webhook-signature": req.headers.get("webhook-signature") ?? "",
}) as typeof event;
} catch {
return new Response("bad signature", { status: 400 });
}
// Deduplicate on webhook-id, then handle the event.
if (event.type === "batch.completed") {
// fetch results for event.data.batch_id
}
return new Response(null, { status: 204 });
}Python
pip install standardwebhooksimport os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError
app = Flask(__name__)
wh = Webhook(os.environ["UTMOST_WEBHOOK_SECRET"]) # "whsec_..."
@app.post("/webhooks/utmost")
def utmost_webhook():
try:
event = wh.verify(request.get_data(as_text=True), {
"webhook-id": request.headers.get("webhook-id", ""),
"webhook-timestamp": request.headers.get("webhook-timestamp", ""),
"webhook-signature": request.headers.get("webhook-signature", ""),
})
except WebhookVerificationError:
return "bad signature", 400
# Deduplicate on webhook-id, then handle the event.
if event["type"] == "spend.cap_reached":
...
return "", 204Delivery and retries
- A delivery succeeds when your endpoint returns any 2xx status within 15 seconds.
- Anything else is a failure: another status, a timeout, a connection error, or a redirect. Redirects are not followed.
- Delivery is at least once. After a failure we retry on this schedule, measured from the previous attempt:
| Attempt | Delay |
|---|---|
| 1 | Immediately |
| 2 | 30 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
| 8 | 24 hours |
After the 8th failed attempt, the delivery is marked failed and not retried. Delivery records are kept for 30 days. Retries are driven by a scheduler that runs about once a minute, so short delays can run a little late.
Deleting an endpoint drops its pending deliveries.
Idempotency
The same event can arrive more than once, and events can arrive out of order. Each endpoint gets its own delivery per event, and webhook-id stays the same across retries of that delivery.
- Store the
webhook-idvalues you have processed, and skip repeats. - Record the id only after your handler succeeds, so a failed attempt is processed on retry.
- Return 2xx quickly and do slow work in the background, to stay within the 15-second timeout.
- Use
timestampin the payload, not arrival order, to sequence events.