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.

Pick the 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.

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

Header	Purpose
`Content-Type`	Always `application/json`.
`User-Agent`	Always `Carebit-Webhooks/1.0`.
`Carebit-Delivery-Id`	Unique id for this delivery. Stable across every retry of the delivery.
`Carebit-Event-Id`	The event id (matches `id` in the JSON body). Use this for dedupe.
`Carebit-Event-Type`	The event type, for example `booking.confirmed`.
`Carebit-Endpoint-Id`	The id of the endpoint the request was routed to.
`Carebit-Signature`	Signed timestamp and HMAC digests. See Webhook signatures.

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.