BillOS v1
Console llms.txt OpenAPI
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.

Body

FieldTypeDescription
urlstringrequiredHTTPS only, publicly reachable (internal and private hosts are refused).
eventsarray of stringSubset to receive. Omitted or empty = all events.
businessIdstringNarrow to one business under your key.

Response

201: { "ok": true, … }

FieldTypeDescription
okbooleanrequired
webhookWebhookEndpointrequiredA 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": … }. Branch on reason.

PreviousList webhook endpoints NextUpdate a webhook endpoint
On this page
BodyResponse
POST /webhooks 
curl -X POST "$BASE/webhooks" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "string"
  }'
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)
import requests
res = requests.post(
    f"{BASE}/webhooks",
    headers={"X-Api-Key": KEY},
    json={
      "url": "string"
    },
)
data = res.json()
Set BASE to https://api.billos.co.il/v1 and KEY to your bk_live_… key, or a bk_test_… key to run it against the sandbox.
Manage your businesses, keys and webhooks in the BillOS Console.