Referência de payload e assinatura do webhook
Toda integração de webhook do FluoTest envia um HTTP POST com um corpo JSON quando um quiz é enviado. Esta página documenta o formato da requisição, os campos padrão do payload, o formato alternativo de payload usado com mapeamento de campos e o esquema de assinatura.
Última atualização
Como é um payload de webhook do FluoTest?
Por padrão, é um objeto JSON plano com os identificadores da resposta, os campos de contato, a pontuação, a faixa ou o resultado, o objeto completo de respostas e a data e hora do envio. Se houver um segredo de assinatura definido, as requisições incluem um cabeçalho X-FluoTest-Signature (HMAC-SHA256 do corpo bruto).
Configuração#
Uma integração de webhook é configurada com uma URL de destino e um segredo de assinatura opcional. Não é preciso OAuth nem conexão com conta de terceiros.
Formato da requisição#
Toda requisição de webhook é enviada com o seguinte método e cabeçalhos:
| Cabeçalho | Valor | Observações |
|---|---|---|
| Método | POST | Sempre uma requisição POST. |
| Content-Type | application/json | O corpo é codificado em JSON. |
| User-Agent | FluoTest-Webhook/1.0 | Identifica que a requisição vem do FluoTest. |
| X-FluoTest-Event | submission.created | O único tipo de evento enviado atualmente. |
| X-FluoTest-Signature | sha256=<hex> | Presente só quando um segredo de assinatura está configurado no webhook. |
Campos padrão do payload#
Sem mapeamento de campos configurado, o corpo da requisição é um 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 | Descrição |
|---|---|---|
| submission_id | string | ID único da resposta. |
| test_id | string | ID do quiz. |
| test_name | string | Nome do quiz. |
| string | null | E-mail do respondente, se coletado. | |
| first_name | string | null | Nome do respondente, se coletado. |
| last_name | string | null | Sobrenome do respondente, se coletado. |
| company | string | null | Nome da empresa, se coletado. |
| contact_type | string | null | Qual forma de contato foi coletada: "email", "phone" ou null. |
| respondent_name | string | null | Nome completo, se uma pergunta de nome foi respondida. |
| total_score | number | A pontuação total do respondente. Em quizzes com pontos negativos, ela é deslocada para cima pela menor pontuação possível, então total_score / max_score é sempre o percentual de 0-100; a pontuação real é o campo score de cada entrada em scores (uma única entrada geral em quizzes com uma só pontuação). |
| max_score | number | A pontuação máxima possível (deslocada do mesmo jeito em quizzes com pontos negativos). |
| score_percent | number | A pontuação expressa como percentual. |
| tier | string | null | Rótulo da faixa de pontuação correspondente (quizzes com uma só pontuação). |
| scores | object | null | Pontuações por categoria em quizzes com várias pontuações; null nos demais casos. |
| outcome | string | null | Chave do resultado principal correspondente (só no mecanismo de resultados do Pro). |
| outcomes | string[] | null | Chaves de todos os resultados correspondentes. |
| outcome_reason | string | null | Explicação em texto simples de por que o respondente recebeu esse resultado: as pontuações e respostas que o definiram, no idioma do dono do quiz. Só no Pro; null nos planos gratuitos e em respostas salvas antes de 7 de outubro de 2026. |
| disqualified | boolean | Se o respondente foi desqualificado. |
| answers | object | Seções/perguntas/respostas aninhadas: veja abaixo. |
| submitted_at | string | Data e hora do envio em ISO 8601. |
| answer_items | object[] | Lista plana de todas as perguntas respondidas: question_id, question, question_type, section e answer (uma lista para seleção múltipla, um link de arquivo para envios de arquivo). |
| phone | string | null | Resposta à pergunta de telefone do quiz, se houver uma. |
| hidden_fields | object | Valores passados no link do quiz para os campos ocultos do quiz, por exemplo {"website": "acme.com", "utm_source": "linkedin"}. Só os nomes definidos no quiz; um objeto vazio quando não há nenhum. |
| links | object | Links de dashboard, results e pdf desta resposta (results/pdf podem ser null). |
Enviar só parte dos campos#
Um webhook pode ser configurado para enviar só um subconjunto escolhido dos campos acima. submission_id e test_id são sempre incluídos, independentemente dessa seleção, para que todo payload possa ser rastreado até a origem.
Modo de payload mapeado#
Quando o mapeamento de campos está configurado para um webhook (veja Mapeamento de campos e novas tentativas de sincronização), o formato do payload muda: os campos mapeados gerados pelas regras de mapeamento substituem a estrutura plana, junto com as tags, e o payload padrão completo é incluído sem alterações em raw.
{
"mapped": { "email": "respondent@example.com", "score": 82 },
"tags": ["High fit"],
"raw": { "submission_id": "8f2b1c3a-...", "...": "..." }
}Verificar a assinatura#
Quando há um segredo de assinatura definido, toda requisição inclui um cabeçalho X-FluoTest-Signature: o digest hexadecimal HMAC-SHA256 do corpo exato da requisição, calculado com o segredo compartilhado e com o prefixo sha256=. Recalcule o mesmo digest sobre o corpo bruto da requisição no lado que recebe e compare-o com o cabeçalho para confirmar que a requisição veio do FluoTest e não foi alterada no caminho.
const crypto = require("crypto");
function isValidSignature(rawBody, header, secret) {
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return header === expected;
}Entrega, novas tentativas e falhas#
Uma requisição de webhook expira depois de 10 segundos. Um status de resposta fora da faixa 2xx é tratado como entrega com falha. Entregas com falha são repetidas automaticamente. Veja Mapeamento de campos e novas tentativas de sincronização para o cronograma de novas tentativas e como as falhas são registradas.
Perguntas frequentes#
O que dispara um webhook do FluoTest?
Um webhook dispara uma vez por resposta de quiz enviada, com o tipo de evento submission.created. No momento não há outro tipo de evento.
Como verifico o cabeçalho X-FluoTest-Signature?
Calcule um digest HMAC-SHA256 do corpo bruto da requisição usando o segredo de assinatura configurado no webhook, codifique-o em hexadecimal, adicione o prefixo sha256= e compare-o com o valor do cabeçalho usando uma comparação de tempo constante.
O que acontece se meu endpoint estiver inacessível ou retornar um erro?
A entrega é marcada como falha e repetida automaticamente com espera progressiva, em até 3 tentativas adicionais, a menos que a falha seja considerada permanente.
Posso escolher quais campos são enviados no payload?
Sim. Um webhook pode ser configurado com uma lista específica de campos; só esses campos, mais submission_id e test_id, são incluídos em cada requisição.
Quizzes no modo anônimo enviam webhooks?
Não. Enquanto um quiz estiver com o modo anônimo (LGPD/GDPR) ativado, todas as integrações dele ficam pausadas, inclusive os webhooks, então nenhuma requisição é enviada para as respostas dele. As respostas coletadas enquanto ele estava ativado também nunca são enviadas depois.