> 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/payload-reference.md).
# Referencia del payload y las cabeceras
El cuerpo JSON y las cabeceras HTTP exactas que dForms envía a un webhook: los objetos form, submission, data, utm y visit, la fase parcial o completa, las cabeceras x-forms-event, x-forms-delivery, x
Cada entrega de webhook es un `POST` con un cuerpo JSON de forma estable. Esta página documenta esa forma campo por campo, las cabeceras que viajan con ella, y qué cambia en una entrega de prueba. Puedes ver el cuerpo exacto de cualquier entrega pasada en el diálogo **Historial del webhook**, en **Lo que enviamos**.
Abre cualquier entrega en Historial del webhook para leer el cuerpo que se envió.
***
## Cuerpo de ejemplo
La forma de abajo es real; los valores están inventados. Las claves dentro de `data` son tus propias **claves de campo** de la pestaña Construir.
```json
{
"id": "submission:6f1c0c2e-7d2a-4c9b-9e41-2f3a1b5c8d90:complete:webhook:0",
"type": "form.submission",
"phase": "complete",
"submittedAt": "2026-08-22T02:13:04.790Z",
"form": {
"id": "19511bc5-a8e0-4445-b9b7-05bfffbb73a2",
"name": "Lead qualification quiz"
},
"submission": {
"id": "6f1c0c2e-7d2a-4c9b-9e41-2f3a1b5c8d90",
"sessionId": "e19fd932-ee1f-4454-bf03-3418bdf54edb",
"score": 12,
"outcome": "Hot lead"
},
"data": {
"email_1": "ada@example.com",
"multiple_choice_2": "option_1",
"firstname": "Jane",
"lastname": "Doe",
"utm": {
"utm_source": "docs",
"utm_medium": "guide",
"utm_campaign": "webhooks"
}
},
"utm": {
"utm_source": "docs",
"utm_medium": "guide",
"utm_campaign": "webhooks"
},
"visit": {
"pageUri": "https://www.example.com/pricing?utm_source=docs&utm_medium=guide&utm_campaign=webhooks",
"pageName": "Pricing | Example",
"embedded": true,
"hutk": "0a1b2c3d4e5f60718293a4b5c6d7e8f9"
}
}
```
## Campos
| Campo | Tipo | Qué significa |
| ---------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | cadena | La clave de idempotencia de esta entrega, el mismo valor que la cabecera `x-forms-delivery`. Formato `submission:{submissionId}:{phase}:webhook:{index}`. Guárdala e ignora una segunda petición con el mismo `id`. |
| `type` | cadena | Siempre `form.submission`. |
| `phase` | cadena | `partial` cuando la persona pasó el punto de envío parcial, `complete` cuando terminó. Una sesión puede producir las dos, en ese orden. |
| `submittedAt` | cadena | Marca de tiempo ISO-8601 (UTC) de esta fase. |
| `form.id` | cadena | El ID del formulario. |
| `form.name` | cadena | El nombre del formulario en el momento del envío. |
| `submission.id` | cadena | El ID de la respuesta. Idéntico en la entrega parcial y en la completa de la misma sesión, que es como las enlazas. |
| `submission.sessionId` | cadena | La sesión de quien responde. |
| `submission.score` | número | Puntaje total según los ajustes de puntaje, recalculado en el servidor. `0` cuando no se usa puntaje. |
| `submission.outcome` | cadena o null | El titular del resultado (rango de puntaje) que coincidió, exactamente como lo vio quien responde. `null` cuando ningún rango coincide o el puntaje está apagado. |
| `data` | objeto | Una entrada por pregunta respondida, indexada por **clave de campo** (por ejemplo `email_1`, `multiple_choice_2`). Las respuestas de opción única y desplegable llevan el **Valor** de la opción; la opción múltiple lleva un array de valores; los deslizadores un número; una pregunta de **Nombre** llega como `firstname` y `lastname`; una de **Subir archivo** llega como un objeto, mira más abajo. Los campos ocultos se incluyen. Las preguntas sin responder no aparecen. `data.utm` contiene los parámetros UTM capturados. |
| `utm` | objeto | Los parámetros UTM capturados del enlace público (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`), repetidos en el nivel superior por comodidad. Un formulario insertado con el fragmento completo los toma de la página que lo inserta cuando su propio enlace no trae ninguno. Objeto vacío cuando no hubo ninguno. |
| `visit` | objeto | La página donde se respondió el formulario. No aparece cuando no se informó ninguna página, por ejemplo en una respuesta enviada por la API sin ella. |
| `visit.pageUri` | cadena o null | La dirección de la página: la página que inserta el formulario, o el enlace propio del formulario (solo con sus parámetros UTM) cuando se abrió directo. Sin el script de inserción en tu página, casi siempre solo la dirección de tu sitio. |
| `visit.pageName` | cadena o null | El título de la página, o el título público del formulario en un enlace directo. |
| `visit.embedded` | booleano | `true` cuando el formulario se respondió dentro de un marco en otra página. |
| `visit.hutk` | cadena | La cookie de HubSpot de la visita (`hubspotutk`, 32 caracteres hexadecimales), para un receptor que sincroniza HubSpot con sus propios flujos. Solo aparece cuando la página carga tu código de seguimiento de HubSpot y la persona no rechazó el seguimiento. Mira [Página de origen y atribución en HubSpot](/dapta-docs-es/dforms/connect/hubspot/attribution.md). |
> **💡 Tip:** En el **Historial del webhook**, **Lo que enviamos** y **Lo que respondió** muestran la cookie de HubSpot como `[hidden]`. Tu endpoint recibe el valor real.
## Respuestas de archivo
Una respuesta de [Subir archivo](/dapta-docs-es/dforms/builder/question-types/file-upload.md) es la única entrada de `data` que no es un valor simple. Llega como un objeto:
```json
"file_1": {
"name": "portfolio-cover.png",
"size": "66398",
"mime": "image/png",
"key": "uploads/.../a4398e1d-....png",
"url": "https://app.dforms.ai/file/v1.ZDdmMDg5OTEt....0nFJmgjfB1rQ..."
}
```
| Campo | Qué significa |
| ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `name` | El nombre del archivo en el computador de quien respondió. Es el único que vale la pena mostrarle a alguien. |
| `size` | El tamaño en bytes, como texto. |
| `mime` | El tipo de contenido que reportó el navegador. Nunca se verifica, así que tómalo como una pista y confía en la extensión. |
| `key` | Dónde está guardado el archivo. No es una URL y no es algo que puedas descargar. |
| `url` | Un enlace permanente que abre el archivo sin iniciar sesión. Mira más abajo. |
El payload nunca lleva el contenido del archivo, solo el enlace para abrirlo.
### El enlace al archivo
`url` es el campo que debes usar cuando una persona u otra herramienta necesita el archivo: escríbelo en una columna de una hoja de cálculo, en una nota del CRM o en un mensaje.
* **Sin iniciar sesión.** Cualquiera que lo abra recibe el archivo. Los PDF y las imágenes (`png`, `jpg`, `gif`, `webp`) se abren en la pestaña del navegador; cualquier otro archivo se descarga con su nombre original. Un archivo de más de 25 MB siempre se descarga.
* **No caduca.** Funciona hoy y dentro de un año. Cada clic lleva al navegador a una dirección de almacenamiento nueva que dura unos minutos, así que guarda el `url`, nunca la dirección a la que llegas.
* **Deja de funcionar cuando se borra la respuesta** en **Respuestas**. Desde ahí contesta *no encontrado*.
* **El mismo enlace en las dos fases.** La entrega parcial y la completa llevan el mismo `url` para el mismo archivo.
> **⚠️ Nota:** Trata el `url` como un secreto. Quien lo tenga puede abrir el archivo, y los payloads de webhook suelen terminar en registros de automatizaciones, hojas de cálculo y notas del CRM. Si tu formulario pide documentos de identidad, hojas de vida o cualquier cosa sensible, decide dónde se va a guardar el enlace antes de conectar el webhook.
> **⚠️ Nota:** No mapees una pregunta **Subir archivo** a una propiedad de HubSpot. Las propiedades de HubSpot guardan texto, así que una respuesta de archivo no llega allá como algo que una persona pueda leer. Si quieres que el archivo se pueda abrir desde HubSpot, haz que tu propia automatización escriba el `url` del webhook en una propiedad de texto.
## Cabeceras
| Cabecera | Ejemplo | Qué significa |
| ------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content-type` | `application/json` | El cuerpo siempre es JSON. |
| `x-forms-event` | `form.submission` | El nombre del evento, igual que `type` en el cuerpo. |
| `x-forms-delivery` | `submission:6f1c…:complete:webhook:0` | La clave de idempotencia (igual que `id` en el cuerpo). Única por respuesta, fase y webhook. Los reintentos de la misma entrega la reutilizan. |
| `x-forms-timestamp` | `1787364784` | Tiempo Unix en segundos de cuando se creó la entrega. Úsalo para rechazar peticiones viejas si quieres protección contra repetición. |
| `X-Forms-Signature` | `sha256=b5b239…` | Presente solo cuando hay un **Secreto de firma** definido: `sha256=` + HMAC-SHA256 en hex del cuerpo crudo. Mira [Verificar la firma](/dapta-docs-es/dforms/connect/webhooks/verify-signature.md). |
Los nombres de cabecera no distinguen mayúsculas; la mayoría de frameworks las exponen en minúsculas.
## Entregas de prueba
**Enviar prueba** manda el mismo sobre con respuestas de ejemplo para que tu endpoint vea la forma real. Diferencias con una entrega de verdad:
* `id` y `x-forms-delivery` usan el prefijo `ping:` en lugar de `submission:`.
* `phase` es `partial`, `submission.id` es `test-submission` y `submission.sessionId` es `test-session`.
* `data` contiene `"test": true` más una respuesta de ejemplo por pregunta: `sample@example.com` para Correo, `+15555550123` para Teléfono, `https://example.com` para Sitio web, `5` para Deslizador, `sample-option` para las de elección, `Sample` / `Respondent` para Nombre, un objeto de archivo llamado `sample.pdf` para Subir archivo (su `url` contesta *no encontrado*, porque la respuesta de ejemplo no existe), y `Sample answer` para todo lo demás.
* `utm` va vacío.
* `visit` es un ejemplo fijo: la página `https://example.com/landing?utm_source=test`, con el título `Example landing page`, `embedded: true`, y una cookie de relleno de 32 ceros que ningún portal de HubSpot conoce.
> **💡 Tip:** Trata `id` (o `x-forms-delivery`) como la clave primaria de tu lado. Si tu endpoint contesta lento y dForms reintenta, recibirás la misma clave otra vez y podrás saltártela sin riesgo.
## Qué sigue
* [Verificar la firma](/dapta-docs-es/dforms/connect/webhooks/verify-signature.md)
* [Probar y ver el historial de entregas](/dapta-docs-es/dforms/connect/webhooks/test-and-history.md)
* [Campos ocultos y prellenado por URL](/dapta-docs-es/dforms/builder/hidden-fields-and-url-prefill.md): cómo llegan a `data` las respuestas ocultas y las UTMs.
---
# 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/payload-reference.md?ask=&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.
