Referencia del payload y la firma del webhook

Cada integración de webhook de FluoTest envía un HTTP POST con un cuerpo JSON cuando se envía un quiz. Esta página documenta el formato de la solicitud, los campos del payload por defecto, la forma alternativa del payload que se usa con el mapeo de campos y el esquema de firma.

Última actualización

¿Cómo es un payload de webhook de FluoTest?

Por defecto es un objeto JSON plano con los identificadores de la respuesta, los campos de contacto, la puntuación, el rango o resultado, el objeto completo de respuestas y la fecha y hora del envío. Si hay un secreto de firma configurado, las solicitudes incluyen una cabecera X-FluoTest-Signature (HMAC-SHA256 del cuerpo sin procesar).

Configuración#

Una integración de webhook se configura con una URL de destino y un secreto de firma opcional. No hace falta OAuth ni conectar ninguna cuenta de terceros.

Formato de la solicitud#

Cada solicitud de webhook se envía con el siguiente método y cabeceras:

CabeceraValorNotas
MétodoPOSTSiempre es una solicitud POST.
Content-Typeapplication/jsonEl cuerpo está codificado en JSON.
User-AgentFluoTest-Webhook/1.0Identifica que la solicitud viene de FluoTest.
X-FluoTest-Eventsubmission.createdEl único tipo de evento que se envía actualmente.
X-FluoTest-Signaturesha256=<hex>Solo aparece cuando hay un secreto de firma configurado para el webhook.

Campos del payload por defecto#

Sin mapeo de campos configurado, el cuerpo de la solicitud es un objeto JSON plano:

{
  "submission_id": "8f2b1c3a-...",
  "test_id": "3a9d7e10-...",
  "test_name": "Lead Fit Quiz",
  "email": "respondent@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Acme Inc",
  "contact_type": "email",
  "respondent_name": "Jane Doe",
  "total_score": 82,
  "max_score": 100,
  "score_percent": 82,
  "tier": "High fit",
  "scores": null,
  "outcome": null,
  "outcomes": null,
  "outcome_reason": "Score: 82 of 100 points (82%) → High fit (70–100%)",
  "disqualified": false,
  "answers": {
    "sections": [
      {
        "section_title": "Section 1",
        "questions": [
          {
            "question_id": "q1",
            "question_text": "What's your role?",
            "question_type": "multiple_choice",
            "answer": "Founder"
          }
        ]
      }
    ]
  },
  "answer_items": [
    {
      "question_id": "q1",
      "question": "What's your role?",
      "question_type": "multiple_choice",
      "section": "Section 1",
      "answer": "Founder"
    }
  ],
  "phone": null,
  "hidden_fields": { "website": "acme.com", "utm_source": "linkedin" },
  "links": {
    "dashboard": "https://fluotest.com/en/dashboard/tests/3a9d7e10-.../submissions",
    "results": "https://fluotest.com/to/jane/lead-fit/results/8f2b1c3a-...",
    "pdf": "https://fluotest.com/api/submissions/8f2b1c3a-.../pdf"
  },
  "submitted_at": "2026-07-10T14:32:00.000Z"
}
CampoTipoDescripción
submission_idstringID único de la respuesta.
test_idstringID del quiz.
test_namestringNombre del quiz.
emailstring | nullEmail del encuestado, si se recogió.
first_namestring | nullNombre del encuestado, si se recogió.
last_namestring | nullApellido del encuestado, si se recogió.
companystring | nullNombre de la empresa, si se recogió.
contact_typestring | nullQué método de contacto se recogió: "email", "phone" o null.
respondent_namestring | nullNombre completo, si se respondió una pregunta de nombre.
total_scorenumberLa puntuación total del encuestado. En quizzes con puntos negativos se desplaza hacia arriba según la puntuación más baja posible, así que total_score / max_score es siempre el porcentaje de 0 a 100; la puntuación real es el campo score de cada entrada de scores (una única entrada general en quizzes con una sola puntuación).
max_scorenumberLa puntuación máxima posible (desplazada de la misma forma en quizzes con puntos negativos).
score_percentnumberLa puntuación expresada como porcentaje.
tierstring | nullEtiqueta del rango de puntuación asignado (quizzes con una sola puntuación).
scoresobject | nullPuntuaciones por categoría en quizzes con varias puntuaciones; null en los demás casos.
outcomestring | nullClave del resultado principal asignado (solo con el motor de resultados de Pro).
outcomesstring[] | nullClaves de todos los resultados asignados.
outcome_reasonstring | nullExplicación en texto plano de por qué el encuestado obtuvo este resultado: las puntuaciones y respuestas que lo decidieron, en el idioma del propietario del quiz. Solo Pro; null en los planes gratuitos y en las respuestas guardadas antes del 7 de octubre de 2026.
disqualifiedbooleanSi el encuestado fue descalificado.
answersobjectSecciones, preguntas y respuestas anidadas: ver más abajo.
submitted_atstringFecha y hora del envío en formato ISO 8601.
answer_itemsobject[]Lista plana de todas las preguntas respondidas: question_id, question, question_type, section y answer (una lista para la selección múltiple, un enlace al archivo para las subidas).
phonestring | nullRespuesta a la pregunta de teléfono del quiz, si la tiene.
hidden_fieldsobjectValores pasados en el enlace del quiz para sus campos ocultos, por ejemplo {"website": "acme.com", "utm_source": "linkedin"}. Solo los nombres definidos en el quiz; un objeto vacío si no hay ninguno.
linksobjectEnlaces dashboard, results y pdf de esta respuesta (results/pdf pueden ser null).

Enviar solo algunos campos#

Un webhook se puede configurar para enviar solo una selección de los campos anteriores. submission_id y test_id se incluyen siempre, sea cual sea esa selección, para que cada payload se pueda rastrear hasta su origen.

Modo de payload mapeado#

Cuando un webhook tiene configurado un mapeo de campos (consulta Mapeo de campos y reintentos de sincronización), la forma del payload cambia: los campos mapeados que generan las reglas de mapeo sustituyen a la estructura plana, junto con las etiquetas, y el payload por defecto completo se incluye sin modificar en raw.

{
  "mapped": { "email": "respondent@example.com", "score": 82 },
  "tags": ["High fit"],
  "raw": { "submission_id": "8f2b1c3a-...", "...": "..." }
}

Verificar la firma#

Cuando hay un secreto de firma configurado, cada solicitud incluye una cabecera X-FluoTest-Signature: el resumen hexadecimal HMAC-SHA256 del cuerpo exacto de la solicitud, calculado con el secreto compartido y con el prefijo sha256=. Calcula el mismo resumen sobre el cuerpo sin procesar en el extremo receptor y compáralo con la cabecera para confirmar que la solicitud viene de FluoTest y no se modificó por el camino.

const crypto = require("crypto");

function isValidSignature(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return header === expected;
}

Entrega, reintentos y fallos#

Una solicitud de webhook caduca a los 10 segundos. Un código de estado de respuesta que no sea 2xx se considera una entrega fallida. Las entregas fallidas se reintentan automáticamente. Consulta Mapeo de campos y reintentos de sincronización para ver el calendario de reintentos y cómo se registran los fallos.

Preguntas frecuentes#

¿Qué activa un webhook de FluoTest?

Un webhook se activa una vez por cada respuesta enviada a un quiz, con el tipo de evento submission.created. Actualmente no hay ningún otro tipo de evento.

¿Cómo verifico la cabecera X-FluoTest-Signature?

Calcula un resumen HMAC-SHA256 del cuerpo sin procesar de la solicitud usando el secreto de firma configurado para el webhook, codifícalo en hexadecimal, añádele el prefijo sha256= y compáralo con el valor de la cabecera mediante una comparación de tiempo constante.

¿Qué pasa si mi endpoint no está disponible o devuelve un error?

La entrega se marca como fallida y se reintenta automáticamente con espera progresiva, hasta 3 intentos adicionales, salvo que el fallo se considere permanente.

¿Puedo elegir qué campos se envían en el payload?

Sí. Un webhook se puede configurar con una lista concreta de campos; solo esos campos, más submission_id y test_id, se incluyen en cada solicitud.

¿Los quizzes en modo anónimo envían webhooks?

No. Mientras un quiz tiene activado el modo anónimo (RGPD), todas sus integraciones están en pausa, incluidos los webhooks, así que no se envía ninguna solicitud por sus respuestas. Las respuestas recogidas mientras estaba activado tampoco se envían nunca más tarde.