Alerts and webhooks

Events

Spend and budgets:

Keys:

Billing and Auditor:

A pause for unusual spend is emailed in that hour's unusual spend email, or on its own when the team's hour was not unusual; a found key gets its own email; a failed auto reload charge its own email. A pause by hand, new and revoked keys, top-ups and Auditor reviews are webhook only.

Payload

Every event is a JSON object with the same four fields. id is the event's identity: the same event is never sent twice to an endpoint unless you replay it, so your handler should treat a repeated id as already handled.

{
  "id": "budget:bp_01j9…:80",
  "type": "budget.threshold",
  "created_at": "2026-10-11T17:02:11.204Z",
  "data": {
    "scope": "project",
    "scope_id": "prj_…",
    "period": "month",
    "period_start": "2026-10-01T00:00:00.000Z",
    "period_end": "2026-11-01T00:00:00.000Z",
    "percent": 80,
    "spent_usd": "80.412000000000",
    "budget_usd": "100.000000000000"
  }
}

Amounts are decimal strings in USD. Requests also carry IB-Event-Id, IB-Event-Type and IB-Delivery-Id headers.

Endpoints and projects

Owners and admins add endpoints under Webhooks, in the sidebar's team links, or with the management API; a team can have five. Each takes every event (All events, which includes types added later) or only the types you check, and Send test sends a webhook.test event to check it. Edit changes its URL, events or project without changing its secret.

An endpoint can be scoped to one project. It then gets only that project's events: its budgets and those of its environments, keys and tags, its keys being created, paused, revoked or found, and its end users running out of budget. The team's own events (the team budget, low balance, unusual spend, top-ups, auto reload, Auditor) go only to endpoints for the whole team. Emails are sent whether or not you have an endpoint.

Verify the signature

Each request has an IB-Signature header: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> under the endpoint's signing secret. While an old secret is being rotated out the header has a second v1, made with the old secret; accept the request if any v1 matches. Check it before trusting the body, and reject timestamps more than five minutes old so a captured request cannot be replayed.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verify(rawBody: string, header: string, secret: string): boolean {
  const t = /(?:^|,)t=(\d+)/.exec(header)?.[1];
  // One v1 per signing secret: two while an old secret is being rotated out.
  const sigs = [...header.matchAll(/(?:^|,)v1=([0-9a-f]{64})(?=,|$)/g)].map((m) => m[1]);
  if (!t || !sigs.length || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return sigs.some((v1) => timingSafeEqual(Buffer.from(v1, "hex"), want));
}

Rotate the secret

Rotate secret on the Webhooks page (or POST /v1/webhooks/{id}/rotate) makes a new secret and shows it once. For the overlap you choose (none, an hour, 24 hours or 7 days; 24 hours by default) every delivery is signed with both secrets, so a receiver that checks for any matching v1 keeps working while you deploy the new secret. When the overlap ends only the new secret signs. Rotating again during an overlap drops the oldest secret at once.

Delivery, retries and replay

• Answer with any 2xx within 10 seconds. Do slow work after answering.
• Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and twice more 12 hours apart, then marked failed.
• After 15 deliveries in a row fail, the endpoint is disabled. Fix it and choose Enable.
• Endpoints must be public HTTPS URLs on the default port. Redirects are not followed.

Deliveries on the Webhooks page lists every delivery, newest first, by endpoint and status, with the body that was sent (API). Replay sends a delivered or failed one again: the same body and event id, signed with the endpoint's current secret, its retries starting over (API). Use it after fixing a receiver that failed, or to process an event again.