Endpoint

Webhooks

Register an endpoint and Brightloom posts events to it as they happen. This is the only reliable way to receive events.

POST/v1/webhooks

Parameters

NameTypeRequiredDescription
urlstringRequiredHTTPS endpoint. Must respond 2xx within 5 seconds.
typesarrayRequiredEvent types to deliver. Use ["*"] for all.
clinic_idstringOptionalRestrict deliveries to one clinic.
descriptionstringOptionalShown in the admin so your team knows what this endpoint is.

Request

curl https://api.brightloom.dev/v1/webhooks \
  -H "Authorization: Bearer blk_live_8fk2Qz7mR4tPvXc1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/brightloom",
    "types": ["appointment.cancelled", "offer.accepted"],
    "description": "Ops dashboard feed"
  }'

Response

{
  "id": "whk_7d1p",
  "url": "https://hooks.example.com/brightloom",
  "types": ["appointment.cancelled", "offer.accepted"],
  "secret": "whsec_3Rk9pLm2Qv",
  "status": "active",
  "created_at": "2026-07-29T09:24:40Z"
}

Gotchas

  • The secret is returned once, at creation. Verify every delivery’s Brightloom-Signature header against it.
  • Signatures include a timestamp. Reject anything older than five minutes to prevent replay.
  • Delivery retries follow an exponential schedule for 24 hours, then the endpoint is disabled and we email the account owner.
  • Deliveries are at-least-once, not exactly-once. Deduplicate on the event id.