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:
| Cabecera | Valor | Notas |
|---|---|---|
| Método | POST | Siempre es una solicitud POST. |
| Content-Type | application/json | El cuerpo está codificado en JSON. |
| User-Agent | FluoTest-Webhook/1.0 | Identifica que la solicitud viene de FluoTest. |
| X-FluoTest-Event | submission.created | El único tipo de evento que se envía actualmente. |
| X-FluoTest-Signature | sha256=<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"
}| Campo | Tipo | Descripción |
|---|---|---|
| submission_id | string | ID único de la respuesta. |
| test_id | string | ID del quiz. |
| test_name | string | Nombre del quiz. |
| string | null | Email del encuestado, si se recogió. | |
| first_name | string | null | Nombre del encuestado, si se recogió. |
| last_name | string | null | Apellido del encuestado, si se recogió. |
| company | string | null | Nombre de la empresa, si se recogió. |
| contact_type | string | null | Qué método de contacto se recogió: "email", "phone" o null. |
| respondent_name | string | null | Nombre completo, si se respondió una pregunta de nombre. |
| total_score | number | La 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_score | number | La puntuación máxima posible (desplazada de la misma forma en quizzes con puntos negativos). |
| score_percent | number | La puntuación expresada como porcentaje. |
| tier | string | null | Etiqueta del rango de puntuación asignado (quizzes con una sola puntuación). |
| scores | object | null | Puntuaciones por categoría en quizzes con varias puntuaciones; null en los demás casos. |
| outcome | string | null | Clave del resultado principal asignado (solo con el motor de resultados de Pro). |
| outcomes | string[] | null | Claves de todos los resultados asignados. |
| outcome_reason | string | null | Explicació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. |
| disqualified | boolean | Si el encuestado fue descalificado. |
| answers | object | Secciones, preguntas y respuestas anidadas: ver más abajo. |
| submitted_at | string | Fecha y hora del envío en formato ISO 8601. |
| answer_items | object[] | 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). |
| phone | string | null | Respuesta a la pregunta de teléfono del quiz, si la tiene. |
| hidden_fields | object | Valores 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. |
| links | object | Enlaces 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.