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
| Event | Fires when |
|---|---|
| invoice.created | A spending snapshot is finalized for a key. |
| provider.status_changed | A provider enters or exits degradation. |
| key.revoked | An API key is revoked. |
| key.nearing_limit | A 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.
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.idfield dedupes. - Acknowledgements should be a plain 200; slower work happens off the request path.