> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/integrations/webhooks.md).

# Webhooks

Send a signed JSON POST to a URL you control each time a dCal booking is created, rescheduled or cancelled. Add a webhook, pick its events, test it with Ping, read its deliveries, and learn how delive

A webhook tells another system the moment something happens to a booking: dCal sends a signed JSON `POST` to a URL you control when a booking is created, rescheduled or cancelled. Use it to update a CRM, start an automation or post a message to your team.

Webhooks belong to the whole workspace. One webhook receives the events of every booking in it: any host, any event, personal or team.

This page covers setting a webhook up. What each message contains is on [Payload reference](https://docs.dapta.ai/dcal/integrations/webhooks/payload-reference.md), and how to check it came from dCal is on [Verify the signature](https://docs.dapta.ai/dcal/integrations/webhooks/verify-signature.md).

***

## Before you start

* You are an admin or owner of your dCal workspace. Only they see **API and webhooks** in the left menu.
* You have an endpoint on the public internet that starts with `https://` and answers within 10 seconds.

***

**Step 1:** In the left menu, click **API and webhooks** > **Webhooks**, or open [app.dcal.ai/admin/developers/webhooks](https://app.dcal.ai/admin/developers/webhooks). Click **Add webhook** at the top right of the page.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-f101fba369ca43ed6f871ad312fd0655d7ba3045%2Fdcal-webhooks-01-webhooks-section.png?alt=media" alt="The Webhooks page with its title, its description, the line No webhooks. and the Add webhook button boxed"><figcaption><p><strong>Webhooks</strong> has its own page under <strong>API and webhooks</strong> in the left menu.</p></figcaption></figure>

***

**Step 2:** In **Subscriber URL**, paste your endpoint. Under **Events**, tick the events you want: **Booking created**, **Booking rescheduled** and **Booking cancelled**. Each tick shows its event name beside it, such as `booking.created`, the name your endpoint receives. **Booking created** is ticked for you. Click **Add webhook**.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-2b638b405367e6b5e6148e1d36258c9c4dc6ebf6%2Fdcal-webhooks-02-add-dialog.png?alt=media" alt="The Add webhook dialog with the Subscriber URL https://example.com/webhooks/dcal and the Events checkboxes Booking created, Booking rescheduled and Booking cancelled, each with its event name beside it, where only Booking created is ticked, above the Cancel and Add webhook buttons"><figcaption><p>A URL and the events to send to it.</p></figcaption></figure>

* Tick at least one event. A webhook with no events never receives anything.
* Write down which events you ticked. The list of webhooks shows only the URL, and the events cannot be edited later. To change them, add a new webhook with the right events and delete the old one.
* The URL must start with `https://` and point to a public address. Addresses such as `localhost`, private networks and names ending in `.local` or `.internal` are refused, and so is a name that does not resolve. dCal checks this when you add the webhook and again before every delivery. A refused URL shows a message that starts with **Subscriber URL rejected**.

***

**Step 3:** Copy the signing secret now. It appears once, above the list of webhooks, and starts with `whsec_`. Store it in your server's settings: your endpoint uses it to [verify the signature](https://docs.dapta.ai/dcal/integrations/webhooks/verify-signature.md) of every delivery.

> **⚠️ Note:** dCal never shows the signing secret again. If you lose it, add a new webhook for the same URL, update your server with the new secret, then delete the old webhook.

***

**Step 4:** Click **Ping** on the webhook's row. dCal sends a signed test message, `{"event":"ping","data":{"ok":true}}`, to your URL and shows the result under the row: **Delivered** with the status code, for example **Delivered (200)**, only when your endpoint answers with a 2xx status. Any other answer shows **Failed**, without the status code or a reason; check your endpoint's logs to see what it returned.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-6c3dd7cc0ae612ddca17405f9a5ae19a747f10d4%2Fdcal-webhooks-03-row-and-ping.png?alt=media" alt="The row of the webhook https://example.com/webhooks/dcal with the active switch and the Ping, Deliveries and Delete buttons, and under it the boxed Ping result Failed, with no status code"><figcaption><p><strong>Failed</strong>: the endpoint did not answer with a 2xx status. A 2xx shows <strong>Delivered</strong> with the code instead.</p></figcaption></figure>

| Ping result                                                       | What to check                                                                                                     |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Delivered** with a status code, for example **Delivered (200)** | Your endpoint answered with a 2xx status. You are ready.                                                          |
| **Failed**                                                        | Your endpoint answered, but not with a 2xx status. The status code is not shown here: check your endpoint's logs. |
| **Subscriber unreachable.**                                       | dCal could not connect, or your endpoint took longer than 10 seconds.                                             |
| **URL is not allowed.**                                           | The URL no longer resolves to a public address.                                                                   |

A ping is a test only: it does not appear in the webhook's deliveries.

***

**Step 5:** Click **Deliveries** to open the webhook's history. It lists the latest 20 real deliveries, newest first, each with its event, a mark for delivered or failed, the status code or error, and the time. Until a real booking event fires, it reads **No deliveries yet**.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-1ce26564a49cb88e2692245c617d06504b47ee44%2Fdcal-webhooks-04-deliveries.png?alt=media" alt="The Deliveries list of the webhook open, newest first: every row is a failed booking.created delivery, with a red cross, HTTP 405 and its date and time"><figcaption><p>Every real attempt is listed, including retries.</p></figcaption></figure>

***

## The events

| Event                 | Tick                    | Fires when                                                                                                                                                                                                                   |
| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking.created`     | **Booking created**     | A booking is made: on a booking page or team page, by you from **Bookings**, by a Dapta agent or through the API. It fires for confirmed bookings and for requests waiting for your OK; the `status` field tells them apart. |
| `booking.rescheduled` | **Booking rescheduled** | The guest moves the booking from the link in their email, or your system moves it through the API.                                                                                                                           |
| `booking.cancelled`   | **Booking cancelled**   | The guest, you or the API cancels a booking. It also fires when you **decline** a request.                                                                                                                                   |

* **Every booking event carries the booking's campaign.** When the booking was made on a booking page from a link with UTM tags, each of its events carries them in `utm`. See [Track where bookings come from](https://docs.dapta.ai/dcal/share/your-booking-page.md#track-where-bookings-come-from).
* **Declined requests arrive as `booking.cancelled`.** A `booking.cancelled` for a booking whose `booking.created` came with `status` `pending` means that request is off, whether you declined it or the guest withdrew it.
* **A move made through the** [**Cal.com-compatible API**](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md) **gives the booking a new `uid`.** Its `booking.rescheduled` carries the new `uid` and the old one in `rescheduledFromUid`, with no times. See [Payload reference](https://docs.dapta.ai/dcal/integrations/webhooks/payload-reference.md).
* **Confirming a request does not reach the webhooks you add here.** dCal has a `booking.confirmed` event, but the **Add webhook** dialog does not offer it, and API keys cannot create webhooks. If you work with requests, read the booking's current `status` through the [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md) to see when it is confirmed.

***

## How a delivery behaves

* dCal sends a `POST` with a JSON body and the headers `content-type`, `X-Slate-Event`, `X-Slate-Signature` and `X-Slate-Delivery`. See [Payload reference](https://docs.dapta.ai/dcal/integrations/webhooks/payload-reference.md).
* Your endpoint has 10 seconds to answer. Any 2xx status counts as delivered. Redirects are not followed and count as a failure, like 4xx and 5xx answers, timeouts and network errors.
* A failed delivery is tried again, with a wait of about 1 second that doubles after each failure, up to 15 minutes between attempts. dCal keeps trying until the delivery has been failing for 24 hours. Then it is marked as failed and not sent again, and its **Deliveries** list gets a line that starts with `Gave up after`.
* The events about one booking reach your endpoint one at a time, in the order they happened. While one waits for a retry, the ones after it wait too, so a `booking.cancelled` never arrives before the `booking.created` it follows.
* A slow or failing endpoint only delays its own deliveries. Emails, calendar updates and your other webhooks keep going.
* A booking never waits for a webhook: deliveries go out in the background.
* Nothing is sent to a webhook while its **active** switch is off, and messages waiting for it are dropped.

> **⚠️ Note:** A delivery can arrive more than once, for example when your endpoint answered after dCal stopped waiting. Every attempt of one delivery carries the same `X-Slate-Delivery` ID: keep the IDs you already handled and skip repeats.

> **💡 Tip:** If your endpoint was down for more than 24 hours, catch up with the [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md): list the bookings for that period and compare them with what you received.

***

## Pause or delete a webhook

* The **active** switch on the row pauses and resumes deliveries. You see **Webhook updated.**
* **Delete** asks **Delete this webhook?** and warns that no more events will be sent to that URL and its signing secret is gone for good. Confirm with **Delete**. You see **Webhook deleted.**

***

## One webhook for the whole workspace

A webhook cannot be limited to one host or one event: it receives every booking in the workspace. To act on some of them only, filter on your side. For a personal event, `booking.created` carries the event's name in `title`: keep the `uid` of the bookings you care about, and match the later `booking.rescheduled` and `booking.cancelled` on that `uid`.

## Related

* [Payload reference](https://docs.dapta.ai/dcal/integrations/webhooks/payload-reference.md): the body and headers of each event.
* [Verify the signature](https://docs.dapta.ai/dcal/integrations/webhooks/verify-signature.md): Node.js and Python examples.
* [HubSpot](https://docs.dapta.ai/dcal/integrations/hubspot.md): send bookings to HubSpot without code.
* [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md): read and change bookings from your system.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dcal/integrations/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
