Webhook setup

Every developer project can register HTTPS endpoints and subscribe each endpoint to one or more event types. When Carebit records a subscribed event, the dispatcher POSTs a signed JSON payload to the endpoint.

1. Create an endpoint

Open Settings > Developer platform > Projects > (your project) > Webhook endpoints, click Add endpoint, and paste the HTTPS URL that will receive deliveries.

2. Copy the signing secret

The dashboard shows the endpoint's signing secret once when the endpoint is created. Store it as a secret in your deployment. Signing secrets use the carebit_whsec_live_... prefix.

If you lose the secret, rotate it from the dashboard. Carebit signs every request with the current secret AND the previous secret for 24 hours after a rotation so a receiver that has both configured can validate either signature.

3. Subscribe to events

Pick the extra event types the endpoint should receive. See Webhook events for the complete list of event types and payload schemas. Webhook subscriptions are independent from API scopes: selecting an event type authorizes that endpoint to receive the payload. API credentials are still governed by project scopes.

Some events are required system events. Carebit always delivers patient_connection_request.created, patient_connection_request.granted, patient_connection_request.denied, and patient_connection_request.expired to every enabled endpoint on the project that created the request. Endpoints on other projects do not receive the request. You do not subscribe to these events, and they do not appear in the subscription picker.

4. Delivery envelope

Every request is POST application/json:

{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-08-17T10:00:00Z",
  "livemode": true,
  "source": "dashboard",
  "developer_platform_project_id": null,
  "type": "booking.confirmed",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "...": "..."
    }
  }
}

5. Request headers

Carebit does not publish stable egress IPs for the dispatcher. Use the signature as the security boundary.

6. Verify and respond

Verify the signature before you trust the body. See Webhook signatures for reference implementations in Node.js, Python, Ruby, and PHP. Return 2XX within 20 seconds. Move slow work off the request thread.