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çalhoValorObservações
MétodoPOSTSempre uma requisição POST.
Content-Typeapplication/jsonO corpo é codificado em JSON.
User-AgentFluoTest-Webhook/1.0Identifica que a requisição vem do FluoTest.
X-FluoTest-Eventsubmission.createdO único tipo de evento enviado atualmente.
X-FluoTest-Signaturesha256=<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"
}
CampoTipoDescrição
submission_idstringID único da resposta.
test_idstringID do quiz.
test_namestringNome do quiz.
emailstring | nullE-mail do respondente, se coletado.
first_namestring | nullNome do respondente, se coletado.
last_namestring | nullSobrenome do respondente, se coletado.
companystring | nullNome da empresa, se coletado.
contact_typestring | nullQual forma de contato foi coletada: "email", "phone" ou null.
respondent_namestring | nullNome completo, se uma pergunta de nome foi respondida.
total_scorenumberA 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_scorenumberA pontuação máxima possível (deslocada do mesmo jeito em quizzes com pontos negativos).
score_percentnumberA pontuação expressa como percentual.
tierstring | nullRótulo da faixa de pontuação correspondente (quizzes com uma só pontuação).
scoresobject | nullPontuações por categoria em quizzes com várias pontuações; null nos demais casos.
outcomestring | nullChave do resultado principal correspondente (só no mecanismo de resultados do Pro).
outcomesstring[] | nullChaves de todos os resultados correspondentes.
outcome_reasonstring | nullExplicaçã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.
disqualifiedbooleanSe o respondente foi desqualificado.
answersobjectSeções/perguntas/respostas aninhadas: veja abaixo.
submitted_atstringData e hora do envio em ISO 8601.
answer_itemsobject[]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).
phonestring | nullResposta à pergunta de telefone do quiz, se houver uma.
hidden_fieldsobjectValores 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.
linksobjectLinks 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.