POST/webhooks

Create a webhook endpoint

POST /webhooks

Requires the businesses scope.

BillOS POSTs subscribed events to url as they happen: signed (HMAC-SHA256), retried with backoff, at-least-once. The full envelope, verification code and retry schedule are in the Webhooks guide.

Endpoints belong to your KEY: one endpoint can cover every business under it, or be narrowed with businessId. A Connect access token may call this too: its endpoint is pinned to the connected business and may subscribe only to events the grant covers (Connect guide, Events and webhooks). The cap of 20 endpoints counts per business.

Body

Field	Type		Description
`url`	string	required	HTTPS only, publicly reachable (internal and private hosts are refused).
`events`	array of string		Subset to receive. Omitted or empty = all events.
`businessId`	string		Narrow to one business under your key.

Response

201: { "ok": true, … }

Field	Type		Description
`ok`	boolean	required
`webhook`	WebhookEndpoint	required	A webhook subscription. Deliveries are POSTed to `url`, signed with `secret` (see the Webhooks guide).

Errors: 400, 401, 403, 404, 429. Every failure answers { "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }: branch on reason, and read hint for what to change (https://docs.billos.co.il/errors.md).

const res = await fetch(`${BASE}/webhooks`, { method: 'POST', headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "url": "string" }), }) const data = await res.json() if (!data.ok) throw new Error(data.reason)