Payloads de Webhook | NueForm Docs

Cada solicitud de webhook de NueForm envía un payload JSON en el cuerpo de la solicitud. Esta página documenta el esquema completo del payload para cada tipo de evento.

Estructura Común

Todos los payloads de webhook comparten estos campos de nivel superior:

Campo	Tipo	Descripción
`event`	`string`	El tipo de evento (por ejemplo, `form.submitted`)
`formId`	`string`	El ID único del formulario
`formTitle`	`string`	El título del formulario en el momento del envío
`responseId`	`string`	El ID único de la respuesta
`answers`	`array`	Array de objetos de respuesta
`submittedAt`	`string`	Marca de tiempo ISO 8601 de cuándo se despachó el evento

Payload de `form.submitted`

Este es el payload enviado cuando un encuestado envía una respuesta completa de formulario.

Ejemplo Completo

json

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

Referencia de Campos

Campos de Nivel Superior

event --- string

Siempre "form.submitted" para este tipo de evento.

formId --- string

El ObjectId de MongoDB del formulario. Es un string hexadecimal de 24 caracteres.

formTitle --- string

El título legible del formulario en el momento en que se dispara el webhook. Ten en cuenta que si renombras el formulario después, los webhooks previamente entregados aún contendrán el título antiguo.

responseId --- string

El ObjectId de MongoDB de la respuesta almacenada. Puedes usar esto para obtener la respuesta completa via la API de Respuestas o como clave de idempotencia para deduplicar entregas de webhook.

submittedAt --- string

Marca de tiempo ISO 8601 que indica cuándo se despachó el webhook. Se genera en el momento del despacho y será muy cercana a (pero no necesariamente idéntica a) el campo submittedAt de la respuesta en la base de datos.

Objetos de Respuesta

Cada entrada en el array answers representa la respuesta de una sola pregunta:

Campo	Tipo	Descripción
`questionId`	`string`	El ObjectId de MongoDB de la pregunta
`value`	`any`	La respuesta del encuestado (el formato varía según el tipo de pregunta)

Valores de Respuesta por Tipo de Pregunta

El campo value en cada objeto de respuesta varía dependiendo del tipo de pregunta. Aquí está el formato para cada tipo:

Entradas de Texto

Tipo de Pregunta	Tipo de Valor	Ejemplo
`short_text`	`string`	`"Jane Doe"`
`long_text`	`string`	`"I really enjoyed the product..."`
`email`	`string`	`"jane@example.com"`
`phone`	`string`	`"+1 (555) 123-4567"`
`number`	`number`	`42`
`url`	`string`	`"https://example.com"`

Preguntas de Elección

Tipo de Pregunta	Tipo de Valor	Ejemplo
`multiple_choice` (única)	`string`	`"Option A"`
`multiple_choice` (múltiple)	`array<string>`	`["Option A", "Option C"]`
`dropdown`	`string`	`"United States"`
`yes_no`	`boolean`	`true`
`picture_choice` (única)	`string`	`"choice_id_abc123"`
`picture_choice` (múltiple)	`array<string>`	`["choice_id_abc123", "choice_id_def456"]`

Para preguntas multiple_choice, el valor es un string único cuando allowMultiple es false, y un array de strings cuando allowMultiple es true. Si el encuestado selecciona la opción "Otro", el array contendrá su entrada de texto libre como un string.

Preguntas de Calificación

Tipo de Pregunta	Tipo de Valor	Ejemplo	Rango
`rating`	`number`	`4`	1 a `steps` (predeterminado 5)
`opinion_scale`	`number`	`7`	`min` a `max`
`nps`	`number`	`9`	0 a 10

Fecha y Hora

Tipo de Pregunta	Tipo de Valor	Ejemplo
`date`	`string`	`"2025-03-15"`

El formato del string de fecha coincide con la propiedad dateFormat configurada en la pregunta (predeterminado YYYY-MM-DD).

Legal y Declaraciones

Tipo de Pregunta	Tipo de Valor	Ejemplo
`legal`	`boolean`	`true`
`statement`	`string`	`""` (siempre vacío --- las declaraciones no recopilan datos)

Clasificación

Tipo de Pregunta	Tipo de Valor	Ejemplo
`ranking`	`array<string>`	`["Speed", "Price", "Quality"]`

El array refleja el orden elegido por el encuestado, del primero al último.

Matriz

Tipo de Pregunta	Tipo de Valor	Ejemplo
`matrix`	`object`	`{ "Speed": "Satisfied", "Price": "Neutral" }`

El objeto mapea etiquetas de fila a la etiqueta de columna seleccionada para cada fila.

Carga de Archivos

Tipo de Pregunta	Tipo de Valor	Ejemplo
`file_upload`	`string`	`"https://storage.nueform.com/uploads/abc123.pdf"`

El valor es la URL del archivo subido en el almacenamiento de NueForm.

Firma y Dibujo

Tipo de Pregunta	Tipo de Valor	Ejemplo
`signature`	`string`	`"data:image/png;base64,iVBOR..."`
`drawing`	`string`	`"data:image/png;base64,iVBOR..."`

Ambos devuelven un URI de datos PNG codificado en base64 de la imagen capturada.

Grabación

Tipo de Pregunta	Tipo de Valor	Ejemplo
`recording`	`string`	`"https://storage.nueform.com/recordings/abc123.webm"`

El valor es la URL del archivo de grabación subido.

Preguntas Compuestas

Los tipos de preguntas compuestas (contact_info, address, question_group, multi_question_page) producen múltiples entradas de respuesta en el array answers --- una para cada subcampo. Cada respuesta de subcampo usa el propio questionId del subcampo.

Por ejemplo, una pregunta contact_info podría producir:

json

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

Resultados de Cuestionario

Para formularios ejecutándose en modo cuestionario (knowledge_quiz, lead_qualification o match_quiz), la respuesta almacenada incluye un objeto quizResults. Aunque este objeto no está directamente incluido en el payload del webhook, puedes recuperarlo via la API de Respuestas usando el responseId del webhook.

El objeto quizResults tiene la siguiente estructura:

json

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

Campo	Tipo	Descripción
`formMode`	`string`	El modo de cuestionario: `knowledge_quiz`, `lead_qualification` o `match_quiz`
`score`	`number`	La puntuación total del encuestado
`correctAnswers`	`number`	Número de preguntas respondidas correctamente (solo knowledge quiz; `0` para otros modos)
`totalScorableQuestions`	`number`	Total de preguntas que contribuyen a la puntuación
`maxScore`	`number`	La puntuación máxima alcanzable
`matchedEndingId`	`string` o `undefined`	El ID de la pantalla final mostrada al encuestado basándose en su puntuación
`endingTallies`	`object` o `undefined`	Solo match quiz: mapea cada ID de pantalla final a su conteo

Metadatos

La respuesta almacenada también puede incluir un objeto metadata que contiene campos ocultos pasados via parámetros de URL. Esto está disponible via la API de Respuestas pero no se incluye en el payload del webhook.

json

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

Para acceder a los metadatos de una respuesta entregada por webhook, recupérala usando el responseId:

bash

curl https://app.nueform.com/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

Encabezados HTTP

Cada solicitud de webhook incluye estos encabezados HTTP:

Encabezado	Valor
`Content-Type`	`application/json`
`X-NueForm-Signature`	Digest hexadecimal HMAC-SHA256 del cuerpo crudo de la solicitud

Consulta Verificación para cómo validar la firma.

Tamaño del Payload

Los payloads de webhook son típicamente pequeños (menos de 10 KB). El tamaño depende principalmente del número de preguntas y la longitud de las respuestas de texto. Las respuestas de carga de archivos contienen URLs (no contenido de archivos), por lo que no aumentan significativamente el tamaño del payload.

Próximos Pasos

Verificación --- Valida las firmas de webhook
Pruebas --- Prueba payloads de webhook localmente
Eventos --- Tipos de eventos y garantías de entrega