Référence du payload et de la signature des webhooks
Chaque intégration webhook de FluoTest envoie une requête HTTP POST avec un corps JSON quand un quiz est envoyé. Cette page documente le format de la requête, les champs du payload par défaut, la forme alternative du payload utilisée avec la correspondance des champs, et le mécanisme de signature.
Dernière mise à jour
À quoi ressemble le payload d'un webhook FluoTest ?
Par défaut, c'est un objet JSON à plat contenant les identifiants de la réponse, les champs de contact, le score, le palier ou le résultat, l'objet complet des réponses et l'horodatage de l'envoi. Si un secret de signature est défini, les requêtes incluent un en-tête X-FluoTest-Signature (HMAC-SHA256 du corps brut).
Configuration#
Une intégration webhook se configure avec une URL de destination et un secret de signature facultatif. Aucune connexion OAuth ni aucun compte tiers n'est nécessaire.
Format de la requête#
Chaque requête webhook est envoyée avec la méthode et les en-têtes suivants :
| En-tête | Valeur | Remarques |
|---|---|---|
| Méthode | POST | Toujours une requête POST. |
| Content-Type | application/json | Le corps est encodé en JSON. |
| User-Agent | FluoTest-Webhook/1.0 | Indique que la requête provient de FluoTest. |
| X-FluoTest-Event | submission.created | Le seul type d'événement envoyé actuellement. |
| X-FluoTest-Signature | sha256=<hex> | Présent uniquement quand un secret de signature est configuré pour le webhook. |
Champs du payload par défaut#
Sans correspondance des champs configurée, le corps de la requête est un objet JSON à plat :
{
"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"
}| Champ | Type | Description |
|---|---|---|
| submission_id | string | ID unique de la réponse. |
| test_id | string | ID du quiz. |
| test_name | string | Nom du quiz. |
| string | null | E-mail du répondant, s'il a été collecté. | |
| first_name | string | null | Prénom du répondant, s'il a été collecté. |
| last_name | string | null | Nom de famille du répondant, s'il a été collecté. |
| company | string | null | Nom de l'entreprise, s'il a été collecté. |
| contact_type | string | null | Le moyen de contact collecté : "email", "phone" ou null. |
| respondent_name | string | null | Nom complet, si une question de nom a reçu une réponse. |
| total_score | number | Le score total du répondant. Dans les quiz avec des points négatifs, il est décalé vers le haut du score le plus bas possible, de sorte que total_score / max_score donne toujours le pourcentage de 0 à 100 ; le score réel est le champ score de chaque entrée de scores (une seule entrée globale dans les quiz à un seul score). |
| max_score | number | Le score maximal possible (décalé de la même façon dans les quiz avec des points négatifs). |
| score_percent | number | Le score exprimé en pourcentage. |
| tier | string | null | Libellé du palier de score correspondant (quiz à un seul score). |
| scores | object | null | Scores par catégorie pour les quiz à plusieurs scores ; null sinon. |
| outcome | string | null | Clé du résultat principal correspondant (moteur de résultats Pro uniquement). |
| outcomes | string[] | null | Clés de tous les résultats correspondants. |
| outcome_reason | string | null | Explication en texte simple de la raison pour laquelle le répondant a obtenu ce résultat : les scores et les réponses qui l'ont déterminé, dans la langue du propriétaire du quiz. Pro uniquement ; null avec les offres gratuites et pour les réponses enregistrées avant le 7 octobre 2026. |
| disqualified | boolean | Indique si le répondant a été disqualifié. |
| answers | object | Sections, questions et réponses imbriquées : voir ci-dessous. |
| submitted_at | string | Horodatage ISO 8601 de l'envoi. |
| answer_items | object[] | Liste à plat de chaque question ayant reçu une réponse : question_id, question, question_type, section et answer (une liste pour la sélection multiple, un lien de fichier pour les envois de fichiers). |
| phone | string | null | Réponse à la question de téléphone du quiz, s'il en a une. |
| hidden_fields | object | Valeurs transmises dans le lien du quiz pour ses champs cachés, par ex. {"website": "acme.com", "utm_source": "linkedin"}. Uniquement les noms définis sur le quiz ; un objet vide s'il n'y en a aucun. |
| links | object | Liens dashboard, results et pdf de cette réponse (results/pdf peuvent être null). |
Envoyer une partie des champs#
Un webhook peut être configuré pour n'envoyer qu'une sélection des champs ci-dessus. submission_id et test_id sont toujours inclus quelle que soit cette sélection, pour que chaque payload puisse être rattaché à sa source.
Mode payload avec correspondance#
Quand une correspondance des champs est configurée pour un webhook (voir Correspondance des champs et nouvelles tentatives de synchronisation), la forme du payload change : les champs produits par les règles de correspondance remplacent la structure à plat, accompagnés des éventuels tags, et le payload par défaut complet est inclus tel quel sous raw.
{
"mapped": { "email": "respondent@example.com", "score": 82 },
"tags": ["High fit"],
"raw": { "submission_id": "8f2b1c3a-...", "...": "..." }
}Vérifier la signature#
Quand un secret de signature est défini, chaque requête inclut un en-tête X-FluoTest-Signature : le condensé hexadécimal HMAC-SHA256 du corps exact de la requête, calculé avec le secret partagé et préfixé par sha256=. Recalculez le même condensé sur le corps brut de la requête côté réception et comparez-le à l'en-tête pour confirmer que la requête vient bien de FluoTest et n'a pas été modifiée en chemin.
const crypto = require("crypto");
function isValidSignature(rawBody, header, secret) {
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return header === expected;
}Livraison, nouvelles tentatives et échecs#
Une requête webhook expire au bout de 10 secondes. Un code de réponse autre que 2xx est considéré comme une livraison échouée. Les livraisons échouées sont relancées automatiquement. Voir Correspondance des champs et nouvelles tentatives de synchronisation pour le calendrier des nouvelles tentatives et la façon dont les échecs sont journalisés.
Questions fréquentes#
Qu'est-ce qui déclenche un webhook FluoTest ?
Un webhook se déclenche une fois par réponse à un quiz, avec le type d'événement submission.created. Il n'existe actuellement aucun autre type d'événement.
Comment vérifier l'en-tête X-FluoTest-Signature ?
Calculez un condensé HMAC-SHA256 du corps brut de la requête avec le secret de signature configuré pour le webhook, encodez-le en hexadécimal, préfixez-le par sha256= et comparez-le à la valeur de l'en-tête avec une comparaison à temps constant.
Que se passe-t-il si mon endpoint est injoignable ou renvoie une erreur ?
La livraison est marquée comme échouée et relancée automatiquement avec un délai croissant, jusqu'à 3 tentatives supplémentaires, sauf si l'échec est considéré comme définitif.
Puis-je choisir les champs envoyés dans le payload ?
Oui. Un webhook peut être configuré avec une liste précise de champs ; seuls ces champs, plus submission_id et test_id, sont inclus dans chaque requête.
Les quiz en mode anonyme envoient-ils des webhooks ?
Non. Tant que le mode anonyme (RGPD) est activé sur un quiz, toutes ses intégrations sont en pause, webhooks compris : aucune requête n'est donc envoyée pour ses réponses. Les réponses collectées pendant cette période ne sont jamais envoyées par la suite non plus.