<!-- 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 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.

## 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.