> 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/dapta-docs-es/dcal/integrations/webhooks.md).

# Webhooks

Envía un POST JSON firmado a una URL tuya cada vez que una reserva de dCal se crea, se reprograma o se cancela. Agrega un webhook, elige sus eventos, pruébalo, revisa sus entregas y conoce cómo funcio

Un webhook avisa a otro sistema en el momento en que algo le pasa a una reserva: dCal envía un `POST` JSON firmado a una URL tuya cuando una reserva se crea, se reprograma o se cancela. Úsalo para actualizar un CRM, iniciar una automatización o publicar un mensaje para tu equipo.

Los webhooks son de todo el workspace. Un webhook recibe los eventos de todas las reservas del workspace: de cualquier anfitrión y cualquier evento, personal o de equipo.

Esta página explica cómo configurar un webhook. Lo que trae cada mensaje está en [Referencia del contenido](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/payload-reference.md), y cómo comprobar que viene de dCal está en [Verifica la firma](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/verify-signature.md).

***

## Antes de empezar

* Eres administrador o propietario de tu workspace de dCal. Solo ellos ven **API y webhooks** en el menú de la izquierda.
* Tienes un endpoint en internet que empieza por `https://` y responde en menos de 10 segundos.

***

**Paso 1:** En el menú de la izquierda, haz clic en **API y webhooks** > **Webhooks**, o abre [app.dcal.ai/admin/developers/webhooks](https://app.dcal.ai/admin/developers/webhooks). Haz clic en **Añadir webhook**, arriba a la derecha de la página.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-66562082b8dab30dcabc3f92a6a29266534c7848%2Fdcal-webhooks-01-webhooks-section.png?alt=media" alt="La página Webhooks con su título, su descripción, la línea No hay webhooks. y el botón Añadir webhook marcado"><figcaption><p><strong>Webhooks</strong> tiene su propia página dentro de <strong>API y webhooks</strong>, en el menú de la izquierda.</p></figcaption></figure>

***

**Paso 2:** En **URL del suscriptor**, pega tu endpoint. En **Eventos**, marca los que quieras: **Reserva creada**, **Reserva reagendada** y **Reserva cancelada**. Junto a cada casilla aparece el nombre del evento, como `booking.created`, que es el nombre que recibe tu endpoint. **Reserva creada** viene marcada. Haz clic en **Añadir webhook**.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-5368646d9d4399a3c4a3ec2f63437ac1688b8d6d%2Fdcal-webhooks-02-add-dialog.png?alt=media" alt="El diálogo Añadir webhook con la URL del suscriptor https://example.com/webhooks/dcal y las casillas de Eventos Reserva creada, Reserva reagendada y Reserva cancelada, cada una con el nombre del evento al lado, donde solo Reserva creada está marcada, sobre los botones Cancelar y Añadir webhook"><figcaption><p>Una URL y los eventos que se le envían.</p></figcaption></figure>

* Marca al menos un evento. Un webhook sin eventos nunca recibe nada.
* Anota qué eventos marcaste. La lista de webhooks muestra solo la URL, y los eventos no se pueden editar después. Para cambiarlos, agrega un webhook nuevo con los eventos correctos y elimina el anterior.
* La URL tiene que empezar por `https://` y apuntar a una dirección pública. Se rechazan direcciones como `localhost`, redes privadas, nombres que terminan en `.local` o `.internal`, y nombres que no existen. dCal lo revisa al agregar el webhook y otra vez antes de cada entrega. Una URL rechazada muestra un mensaje en inglés que empieza con **Subscriber URL rejected**.

***

**Paso 3:** Copia ahora el secreto de firma. Aparece una sola vez, encima de la lista de webhooks, y empieza por `whsec_`. Guárdalo en la configuración de tu servidor: tu endpoint lo usa para [verificar la firma](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/verify-signature.md) de cada entrega.

> **⚠️ Nota:** dCal no vuelve a mostrar el secreto de firma. Si lo pierdes, agrega un webhook nuevo para la misma URL, actualiza tu servidor con el nuevo secreto y luego elimina el webhook anterior.

***

**Paso 4:** Haz clic en **Probar** en la fila del webhook. dCal envía un mensaje de prueba firmado, `{"event":"ping","data":{"ok":true}}`, a tu URL y muestra el resultado debajo de la fila, en inglés: **Delivered** con el código de estado, por ejemplo **Delivered (200)**, solo cuando tu endpoint responde con un estado 2xx. Cualquier otra respuesta muestra **Failed**, sin el código de estado ni un motivo; revisa los registros de tu endpoint para ver qué respondió.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-727f03e5c024ebe7e237483f597b32a5c1c0cd5a%2Fdcal-webhooks-03-row-and-ping.png?alt=media" alt="La fila del webhook https://example.com/webhooks/dcal con el interruptor activo y los botones Probar, Entregas y Eliminar, y debajo el resultado de la prueba Failed, marcado, sin código de estado"><figcaption><p><strong>Failed</strong>: el endpoint no respondió con un estado 2xx. Con un 2xx verías <strong>Delivered</strong> con el código.</p></figcaption></figure>

| Resultado de la prueba                                                 | Qué revisar                                                                                                                    |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Delivered** con un código de estado, por ejemplo **Delivered (200)** | Tu endpoint respondió con un estado 2xx. Ya está listo.                                                                        |
| **Failed**                                                             | Tu endpoint respondió, pero no con un estado 2xx. Aquí no se muestra el código de estado: revisa los registros de tu endpoint. |
| **Subscriber unreachable.**                                            | dCal no pudo conectarse, o tu endpoint tardó más de 10 segundos.                                                               |
| **URL is not allowed.**                                                | La URL ya no apunta a una dirección pública.                                                                                   |

La prueba es solo eso: no aparece en las entregas del webhook.

***

**Paso 5:** Haz clic en **Entregas** para abrir el historial del webhook. Muestra las últimas 20 entregas reales, de la más nueva a la más antigua, cada una con su evento, una marca de entregada o fallida, el código de estado o el error, y la hora. Mientras no ocurra un evento real de reserva, dice **Aún no hay entregas**.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-60786cf2c0cb5f8638081364516804b34c6e09e8%2Fdcal-webhooks-04-deliveries.png?alt=media" alt="La lista Entregas del webhook abierta, de la más reciente a la más antigua: cada fila es una entrega fallida de booking.created, con una cruz roja, HTTP 405 y su fecha y hora"><figcaption><p>Cada intento real aparece en la lista, reintentos incluidos.</p></figcaption></figure>

***

## Los eventos

| Evento                | Casilla                | Se dispara cuando                                                                                                                                                                                                                    |
| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `booking.created`     | **Reserva creada**     | Se hace una reserva: en una página de reservas o de equipo, tú desde **Reservas**, un agente de Dapta o la API. Se dispara para reservas confirmadas y para solicitudes que esperan tu visto bueno; el campo `status` las distingue. |
| `booking.rescheduled` | **Reserva reagendada** | El invitado mueve la reserva desde el enlace de su correo, o tu sistema la mueve con la API.                                                                                                                                         |
| `booking.cancelled`   | **Reserva cancelada**  | El invitado, tú o la API cancelan una reserva. También se dispara cuando **rechazas** una solicitud.                                                                                                                                 |

* **Todos los eventos de reserva traen la campaña de la reserva.** Cuando la reserva se hizo en una página de reservas desde un enlace con etiquetas UTM, cada uno de sus eventos las trae en `utm`. Mira [Mide el origen de tus reservas](https://docs.dapta.ai/dapta-docs-es/dcal/share/your-booking-page.md#mide-el-origen-de-tus-reservas).
* **Las solicitudes rechazadas llegan como `booking.cancelled`.** Un `booking.cancelled` de una reserva cuyo `booking.created` llegó con `status` `pending` significa que esa solicitud ya no va, ya sea porque la rechazaste o porque el invitado la retiró.
* **Un cambio de horario hecho con la** [**API compatible con Cal.com**](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md) **le da a la reserva un `uid` nuevo.** Su `booking.rescheduled` trae el `uid` nuevo y el anterior en `rescheduledFromUid`, sin horas. Mira [Referencia del contenido](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/payload-reference.md).
* **Confirmar una solicitud no llega a los webhooks que agregas aquí.** dCal tiene un evento `booking.confirmed`, pero el diálogo **Añadir webhook** no lo ofrece, y las claves de API no pueden crear webhooks. Si trabajas con solicitudes, consulta el `status` actual de la reserva con la [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md) para saber cuándo quedó confirmada.

***

## Cómo funciona una entrega

* dCal envía un `POST` con un cuerpo JSON y las cabeceras `content-type`, `X-Slate-Event`, `X-Slate-Signature` y `X-Slate-Delivery`. Mira [Referencia del contenido](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/payload-reference.md).
* Tu endpoint tiene 10 segundos para responder. Cualquier estado 2xx cuenta como entregado. Las redirecciones no se siguen y cuentan como fallo, igual que las respuestas 4xx y 5xx, los tiempos agotados y los errores de red.
* Una entrega fallida se vuelve a intentar, con una espera de cerca de 1 segundo que se duplica después de cada fallo, hasta 15 minutos entre intentos. dCal sigue intentando hasta que la entrega lleva 24 horas fallando. Entonces queda marcada como fallida y no se vuelve a enviar, y su lista **Entregas** recibe una línea que empieza con `Gave up after`.
* Los eventos de una misma reserva llegan a tu endpoint uno a la vez, en el orden en que ocurrieron. Mientras uno espera un reintento, los que vienen después también esperan, así que un `booking.cancelled` nunca llega antes que el `booking.created` al que sigue.
* Un endpoint lento o que falla solo retrasa sus propias entregas. Los correos, las actualizaciones del calendario y tus otros webhooks siguen saliendo.
* Una reserva nunca espera a un webhook: las entregas salen en segundo plano.
* No se envía nada a un webhook mientras su interruptor **activo** está apagado, y los mensajes que esperaban se descartan.

> **⚠️ Nota:** Una entrega puede llegar más de una vez, por ejemplo cuando tu endpoint respondió después de que dCal dejó de esperar. Todos los intentos de una misma entrega traen el mismo ID en `X-Slate-Delivery`: guarda los ID que ya procesaste y omite las repeticiones.

> **💡 Tip:** Si tu endpoint estuvo caído más de 24 horas, ponte al día con la [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md): lista las reservas de ese período y compáralas con lo que recibiste.

***

## Pausar o eliminar un webhook

* El interruptor **activo** de la fila pausa y reanuda las entregas. Verás **Webhook actualizado.**
* **Eliminar** pregunta **¿Eliminar este webhook?** y avisa que no se enviarán más eventos a esa URL y que su secreto de firma se pierde definitivamente. Confirma con **Eliminar**. Verás **Webhook eliminado.**

***

## Un webhook para todo el workspace

Un webhook no se puede limitar a un anfitrión o a un evento: recibe todas las reservas del workspace. Para actuar solo sobre algunas, filtra de tu lado. En un evento personal, `booking.created` trae el nombre del evento en `title`: guarda el `uid` de las reservas que te interesan y relaciona después los `booking.rescheduled` y `booking.cancelled` por ese `uid`.

## Relacionado

* [Referencia del contenido](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/payload-reference.md): el cuerpo y las cabeceras de cada evento.
* [Verifica la firma](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks/verify-signature.md): ejemplos en Node.js y Python.
* [HubSpot](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/hubspot.md): envía las reservas a HubSpot sin código.
* [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md): consulta y cambia reservas desde tu sistema.


---

# 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/dapta-docs-es/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.
