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 standardwebhooks
import { 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 standardwebhooks
import 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 "", 204

Delivery 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-id values 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 timestamp in the payload, not arrival order, to sequence events.