<!-- Carebit docs: Webhook setup -->

# Webhook setup

Every developer project can register HTTPS endpoints and subscribe each
endpoint to one or more [event types](/webhooks). 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](/webhooks) 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`:

```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](/guides/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](/guides/webhook-signatures) for reference
implementations in Node.js, Python, Ruby, and PHP. Return `2XX` within
20 seconds. Move slow work off the request thread.