> 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/dforms/connect/webhooks.md).

# Webhooks

Envía cada respuesta de dForms como un POST JSON a una URL que tú controlas. Define el endpoint, un secreto de firma opcional, elige si las respuestas parciales y completas lo disparan, manda una prue

Un webhook manda cada respuesta como JSON (POST) a un endpoint tuyo: tu CRM, una herramienta de automatización, un conector de hojas de cálculo, o tu propio backend. Se configura por formulario desde la pestaña **Conectar**. La entrega es duradera: la respuesta se guarda primero y el webhook se encola, se reintenta si falla, y se registra para que veas qué se envió y qué contestó tu endpoint.

Esta página cubre la tarjeta del webhook. El formato de la petición está en [Referencia del payload y las cabeceras](/dapta-docs-es/dforms/connect/webhooks/payload-reference.md), la autenticación en [Verificar la firma](/dapta-docs-es/dforms/connect/webhooks/verify-signature.md), y las pruebas en [Probar y ver el historial de entregas](/dapta-docs-es/dforms/connect/webhooks/test-and-history.md).

***

**Paso 1:** Abre tu formulario en el editor y haz clic en **Conectar** en la barra superior. En la sección **Integraciones**, busca la tarjeta de **Webhook** («Envía cada respuesta como JSON (POST) a una URL que tú controlas.») y activa el interruptor. La etiqueta pasa de **Desactivado** a **Activado** y la tarjeta se despliega.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-5c124693074bc29efe2143ebd223140d928e5fdb%2Fforms-webhooks-01-enable-switch.png?alt=media" alt="La tarjeta de Webhook con el interruptor Activado encendido, mostrando los campos URL del endpoint, Secreto de firma y Disparar en"><figcaption><p>Activa el interruptor para revelar los ajustes del webhook.</p></figcaption></figure>

***

**Paso 2:** Pega tu URL en **URL del endpoint**. Tiene que empezar por `https://` (se acepta `http://` pelado solo para `localhost`, para desarrollo local). Cualquier otra cosa muestra «Introduce una URL https\:// válida (http solo se permite para localhost).» En cuanto la URL es válida se guarda: el pie dice **Cambios guardados automáticamente**, y el webhook está en vivo en el formulario publicado desde ese momento.

**Paso 3 (recomendado):** Escribe un **Secreto de firma (opcional)**. Cuando está definido, cada petición se firma con HMAC-SHA256 en la cabecera `X-Forms-Signature`, para que tu endpoint pueda verificar que la petición vino de verdad de dForms. Al salir del campo se enmascara y dice **Hay un secreto guardado: déjalo en blanco para conservarlo o escribe uno nuevo.** El secreto no se vuelve a mostrar nunca.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-905504e8206884d3e7b9b06d49948d5097007a06%2Fforms-webhooks-02-url-and-secret.png?alt=media" alt="La tarjeta de Webhook con una URL del endpoint llena y un Secreto de firma escrito"><figcaption><p>URL del endpoint y secreto de firma. Los dos se guardan solos.</p></figcaption></figure>

***

**Paso 4:** En **Disparar en**, elige qué respuestas se envían: **Respuestas parciales**, **Respuestas completas**, o las dos. Las dos vienen marcadas por defecto y al menos una tiene que quedar marcada.

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-9ae4664699823c7f7dee4551452bb2dac19dbec1%2Fforms-webhooks-03-trigger-on.png?alt=media" alt="Las casillas de Disparar en para Respuestas parciales y Respuestas completas"><figcaption><p>Elige qué respuestas se envían a este webhook.</p></figcaption></figure>

* Una respuesta **parcial** se envía cuando la persona pasa el **Punto de envío parcial** del formulario (por ejemplo justo después de la pregunta de correo) y todavía no ha terminado. En una pantalla de Diapositivas que muestra varias preguntas, se envía cuando la persona envía la pantalla que contiene el punto. Mira [Varias preguntas en una pantalla](/dapta-docs-es/dforms/builder/screens.md).
* Una respuesta **completa** se envía cuando la persona llega al final. La misma sesión produce una entrega parcial y luego una completa; las dos llevan el mismo `submission.id`, y `phase` las distingue.

Con la [protección contra spam](/dapta-docs-es/dforms/connect/spam-protection.md) activa, las respuestas parciales se guardan pero no se envían. **Respuestas parciales** sigue marcada y muestra **En pausa mientras la protección contra spam está activa**, y un webhook que solo escucha parciales avisa *Este webhook no se va a disparar: solo escucha respuestas parciales, que están en pausa mientras la protección contra spam está activa.*

***

**Paso 5:** Haz clic en **Enviar prueba**. dForms manda un cuerpo de ejemplo con la forma real, firmado con tu secreto, con respuestas inventadas, `"test": true` en los datos y un `visit` de ejemplo. Un aviso verde **Prueba entregada: tu endpoint la aceptó.** significa que tu endpoint contestó con un estado 2xx. Si no fue así, el aviso explica qué volvió (mira [Probar y ver el historial de entregas](/dapta-docs-es/dforms/connect/webhooks/test-and-history.md)).

<figure><img src="https://365551146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMUYDYzjmxpzlYaw0gcaZ%2Fuploads%2Fgit-blob-fcb909f4b7e9580f29edfcd0c66c0633da1415c6%2Fforms-webhooks-04-send-test.png?alt=media" alt="El botón Enviar prueba con un aviso que dice Prueba entregada: tu endpoint la aceptó."><figcaption><p>Una prueba correcta. La petición de ejemplo llega a tu endpoint de verdad.</p></figcaption></figure>

> **⚠️ Nota:** **Enviar prueba** está disponible para Owners y Admins. Cualquier miembro puede editar los campos del webhook.

***

## Referencia de ajustes

| Ajuste                                     | Qué hace                                                                                                                                                                      |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interruptor **Activado** / **Desactivado** | Enciende o apaga el webhook sin perder sus ajustes. Apagado significa que no se encola nada para este webhook.                                                                |
| **URL del endpoint**                       | La URL `https://` que recibe el POST. Vaciar el campo quita el webhook. Las direcciones privadas, de loopback, link-local y de metadatos de nube se bloquean antes de enviar. |
| **Enviar prueba**                          | Manda una petición de ejemplo firmada. Desactivado hasta que hay una URL guardada (si no: «Primero guarda una URL de webhook.»).                                              |
| **Secreto de firma (opcional)**            | Clave de la firma HMAC-SHA256 en `X-Forms-Signature`. Déjalo en blanco para conservar el actual; escribe un valor nuevo para rotarlo.                                         |
| **Disparar en**                            | **Respuestas parciales** o **Respuestas completas**. Al menos una.                                                                                                            |
| **Historial del webhook**                  | Una etiqueta de **{n} entregas** (o un **{n} con error** rojo) y el botón **Ver historial** que abre el registro de entregas.                                                 |

## Cómo se comporta una entrega

* Método **POST**, cabecera `content-type: application/json`, cuerpo = el sobre JSON descrito en [Referencia del payload y las cabeceras](/dapta-docs-es/dforms/connect/webhooks/payload-reference.md).
* Tu endpoint tiene 10 segundos para contestar. Cualquier **2xx** cuenta como entregada. Un 3xx nunca se sigue y cuenta como fallo, igual que 4xx, 5xx, tiempos agotados y errores de red.
* Los fallos se reintentan solos con retrasos crecientes (1 s, 2 s, 4 s, 8 s…), hasta 5 intentos. Después la entrega queda marcada con **Falló** y se conserva en el historial. Mira [Entrega, reintentos e historial](/dapta-docs-es/dforms/connect/delivery-and-retries.md).
* No se envía nada a un webhook **Desactivado**, y una respuesta siempre se guarda aunque el webhook esté caído.
* Con la [protección contra spam](/dapta-docs-es/dforms/connect/spam-protection.md) activa, solo se envían las respuestas completas y verificadas.

## Varios webhooks en un formulario

Cada formulario puede tener más de un webhook, pero la tarjeta edita solo el primero. Cuando existen otros ves **Este formulario tiene {count} webhook(s) más** con la nota de que siguen funcionando exactamente como están y se guardan sin tocar, solo que no se editan desde aquí. Todos aparecen en el inventario de **Webhooks** de la página de [Conexiones](/dapta-docs-es/dforms/connect/connections.md).

> **💡 Tip:** Los parámetros UTM del enlace público (`utm_source`, `utm_medium`, …) viajan en el cuerpo de cada webhook, anidados en `data.utm` y otra vez en el nivel superior en `utm`, para que tu endpoint pueda atribuir el lead. Un formulario insertado con el fragmento completo los toma de la página que lo inserta cuando su propio enlace no trae ninguno. La página en sí viaja en `visit`: mira [Referencia del payload y las cabeceras](/dapta-docs-es/dforms/connect/webhooks/payload-reference.md).

## Qué sigue

* [Referencia del payload y las cabeceras](/dapta-docs-es/dforms/connect/webhooks/payload-reference.md): todos los campos y cabeceras.
* [Verificar la firma](/dapta-docs-es/dforms/connect/webhooks/verify-signature.md): fragmentos en Node.js y Python.
* [Probar y ver el historial de entregas](/dapta-docs-es/dforms/connect/webhooks/test-and-history.md): cómo leer el diálogo de historial.
* [Respuestas parciales](/dapta-docs-es/dforms/builder/partial-submissions.md): dónde va el punto de envío parcial.


---

# 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/dforms/connect/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.