Beta docs: the shipped API is POST /api/v1/generate for gemini and sarvam. Some pages below describe planned features. See the shipped quick start.

Guides

Webhooks

Receive gateway events over HTTP instead of polling.

Planned — not shipped

Webhooks are on the immediate roadmap. The interface below is the committed design; endpoints are not live yet.

Webhooks give the gateway a way to reach you: cost roll-ups, provider status changes, and key lifecycle events — delivered as signed HTTP POSTs to a URL you own.

Events

EventFires when
invoice.createdA spending snapshot is finalized for a key.
provider.status_changedA provider enters or exits degradation.
key.revokedAn API key is revoked.
key.nearing_limitA key crosses 80% of its monthly budget.

Verifying signatures

Each delivery is signed with HMAC-SHA256 using the webhook's secret. The signature travels in x-openlink-signature; always verify before acting on a payload.

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

function verify(req, secret) {
  const sig = req.headers["x-openlink-signature"];
  const expected = createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");
  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery contract

  • Deliveries retry with backoff until a 2xx, for up to 24 hours.
  • Payloads are idempotent — the event.id field dedupes.
  • Acknowledgements should be a plain 200; slower work happens off the request path.