Xbow Webhooks API

Manage webhook subscriptions and receive event notifications. When creating an organization, you may provide an HTTPS webhook URL to receive events related to the organization's resources. We implement _best-effort_ delivery of events, soon after they occur. We will not retry delivery if it fails for any reason. ## Webhook Versioning Webhook payloads follow the API version of the subscription. When a version reaches its end-of-life date, webhook subscriptions for that version will stop emitting events. Ensure your integration is updated to a supported version before the EOL date. ## Signature Verification Each request will be a `POST` request sent with the following headers: * `X-Signature-Timestamp`: A Unix timestamp in seconds. * `X-Signature-Ed25519`: An hex string representing an Ed25519 signature of the concatenation of the timestamp and the request body, signed with XBOW's private key. You must verify the signature using the public key from the `GET /api/v1/meta/webhooks-signing-keys` endpoint. You must verify that the timestamp is within a valid range from the current time to prevent replay attacks. An example of a valid range might be +/-5 minutes. You should respond with a 2xx status code if the signature is valid, and a 401 status code otherwise. Before organization creation, we will send two test `ping` events. One signed with XBOW's private key, and one signed with an invalid key. This allows you to verify that your signature verification is working correctly. For example, if you're using Node.js: ```javascript import consumers from "node:stream/consumers"; // Fetch the public key from the API (cache this - it rarely changes) const keysResponse = await fetch("https://console.xbow.com/api/v1/meta/webhooks-signing-keys", { headers: { Authorization: "Bearer your-api-key", "X-XBOW-API-Version": "2026-02-01" } }); const keys = await keysResponse.json(); const publicKeyBase64 = keys[0].publicKey; // Import the public key (SPKI format, base64-encoded) const publicKey = await crypto.subtle.importKey( "spki", Buffer.from(publicKeyBase64, "base64"), { name: "Ed25519" }, false, ["verify"], ); const timestamp = req.headers["x-signature-timestamp"]; const timestampTime = parseInt(timestamp, 10); const now = Math.floor(Date.now() / 1000); const isValidTimestamp = (Math.abs(now - timestampTime) 2026-04-01. Skip "next". const BASE = "https://console.xbow.com"; const ORG_ID = "your-organization-id"; const API_KEY = "your-api-key"; const OLD = "2026-02-01"; const NEW = "2026-04-01"; const headers = { Authorization: `Bearer ${API_KEY}`, "X-XBOW-API-Version": NEW }; async function* paginate(url: string): AsyncGenerator { let cursor: string | null = null; do { const u = new URL(url); if (cursor) u.searchParams.set("cursor", cursor); const res = await fetch(u, { headers }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const page = (await res.json()) as { items: T[]; nextCursor: string | null }; yield* page.items; cursor = page.nextCursor; } while (cursor); } type Sub = { id: string; apiVersion: string }; for await (const wh of paginate(`${BASE}/api/v1/organizations/${ORG_ID}/webhooks`)) { if (wh.apiVersion === "next") { console.log(`skip ${wh.id} (next)`); continue; } if (wh.apiVersion !== OLD) { console.log(`skip ${wh.id} (${wh.apiVersion})`); continue; } const res = await fetch(`${BASE}/api/v1/webhooks/${wh.id}`, { method: "PATCH", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ apiVersion: NEW }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); console.log(`bump ${wh.id} ${OLD} -> ${NEW}`); } ``` An `apiVersion`-only `PATCH` does not re-validate your endpoint, so the upgrade is cheap and safe to run for many subscriptions at once. A `PATCH` that changes `targetUrl` does re-send the validation pings described above, and must receive a 2xx for the valid ping to succeed.