> 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/dapta-forms/connect/webhooks/payload-reference.md).
# Referencia del payload y las cabeceras
El cuerpo JSON y las cabeceras HTTP exactas que Dapta Forms envía a un webhook: los objetos form, submission, data y utm, la fase parcial o completa, las cabeceras x-forms-event, x-forms-delivery, x-f
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 de webhook**, en **Qué enviamos**.
Abre cualquier entrega en Historial de 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": "Ada",
"lastname": "Lovelace",
"utm": {
"utm_source": "docs",
"utm_medium": "guide",
"utm_campaign": "webhooks"
}
},
"utm": {
"utm_source": "docs",
"utm_medium": "guide",
"utm_campaign": "webhooks"
}
}
```
## 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. Objeto vacío cuando el enlace no traía ninguno. |
## Respuestas de archivo
Una respuesta de [Subir archivo](/dapta-docs-es/dapta-forms/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"
}
```
| 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. |
El payload nunca lleva el archivo ni un enlace a él. Los enlaces a archivos subidos se crean de a un clic y caducan en minutos, que es justo lo que un payload de webhook no puede contener. Si tu integración necesita el archivo, sácalo desde **Respuestas** o pide que alguien lo descargue. Mira [Archivos subidos](/dapta-docs-es/dapta-forms/results/uploaded-files.md).
> **⚠️ 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. Deja la pregunta sin mapear y abre el archivo desde **Respuestas**.
## 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/dapta-forms/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, y `Sample answer` para todo lo demás.
* `utm` va vacío.
> **💡 Tip:** Trata `id` (o `x-forms-delivery`) como la clave primaria de tu lado. Si tu endpoint contesta lento y Dapta Forms reintenta, recibirás la misma clave otra vez y podrás saltártela sin riesgo.
## Qué sigue
* [Verificar la firma](/dapta-docs-es/dapta-forms/connect/webhooks/verify-signature.md)
* [Probar y ver el historial de entregas](/dapta-docs-es/dapta-forms/connect/webhooks/test-and-history.md)
* [Campos ocultos y prellenado por URL](/dapta-docs-es/dapta-forms/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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.dapta.ai/dapta-docs-es/dapta-forms/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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.
