Payloads de webhook

Toda requisição de webhook do NueForm envia um payload JSON no corpo da requisição. Esta página documenta o schema completo do payload para cada tipo de evento.

Estrutura comum

Todos os payloads de webhook compartilham estes campos de nível superior:

Payload de form.submitted

Este é o payload enviado quando um respondente envia uma resposta completa de formulário.

Exemplo completo

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  },
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

Referência de campos

Campos de nível superior

event --- string

Sempre "form.submitted" para este tipo de evento.

formId --- string

O ObjectId do MongoDB do formulário. É uma string hexadecimal de 24 caracteres.

formTitle --- string

O título legível do formulário no momento em que o webhook dispara. Observe que, se você renomear o formulário depois, os webhooks já entregues continuarão contendo o título antigo.

responseId --- string

O ObjectId do MongoDB da resposta armazenada. Você pode usá-lo para buscar a resposta completa pela API de Respostas ou como chave de idempotência para desduplicar entregas de webhook.

submittedAt --- string

Timestamp ISO 8601 indicando quando o webhook foi despachado. Ele é gerado no momento do despacho e será muito próximo (mas não necessariamente idêntico) ao campo submittedAt da resposta no banco de dados.

respondent --- object ou null

Identidade do usuário logado que enviou a resposta, exposta apenas quando o formulário exigia login (requireLogin: true). null para todos os envios anônimos. Veja Identidade do respondente abaixo para o schema completo e o comportamento.

Objetos de resposta

Cada entrada no array answers representa a resposta de uma única pergunta:

Valores de resposta por tipo de pergunta

O campo value de cada objeto de resposta varia de acordo com o tipo de pergunta. Este é o formato para cada tipo:

Entradas de texto

Perguntas de escolha

Perguntas de avaliação

Data e hora

O formato da string de data corresponde à propriedade dateFormat configurada na pergunta (o padrão é YYYY-MM-DD).

Legal e declarações

Ranking

O array reflete a ordem escolhida pelo respondente, do primeiro ao último.

Matriz

O objeto mapeia os rótulos das linhas para o rótulo da coluna selecionada em cada linha.

Upload de arquivo

O valor é a URL do arquivo enviado no armazenamento do NueForm.

Assinatura e desenho

Ambos retornam um data URI PNG codificado em base64 da imagem capturada.

Gravação

O valor é a URL do arquivo de gravação enviado.

Perguntas compostas

Tipos de pergunta compostos (contact_info, address, question_group, multi_question_page) produzem múltiplas entradas de resposta no array answers --- uma para cada subcampo. A resposta de cada subcampo usa o próprio questionId do subcampo.

Por exemplo, uma pergunta contact_info pode produzir:

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

Identidade do respondente

Quando um formulário é configurado com requireLogin: true, todo envio aceito fica vinculado a um usuário autenticado. Os payloads de webhook expõem essa identidade aos donos do formulário através do campo respondent. Para todos os outros envios, o campo é null.

Schema

{
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  }
}

Quando respondent é preenchido

respondent é preenchido apenas quando:

1. O formulário tem requireLogin definido como true, e
2. Quem enviou fez login porque o formulário exigia antes de enviar.

Quando requireSsoLogin também é true, apenas usuários que são membros da equipe do formulário via SSO conseguem chegar à etapa de envio, então todo respondent preenchido terá auth_method: "sso".

Quando respondent é null

O campo está sempre presente no JSON para um parsing previsível no destino, e é null sempre que qualquer uma destas condições for verdadeira:

• O formulário não exigia login (requireLogin era false).
• Quem enviou era anônimo.
• A resposta foi salva pelo fluxo de consentimento pós-envio (o prompt de "claim this response"). Respostas salvas por consentimento nunca aparecem nos payloads de webhook com identidade anexada — elas são armazenadas apenas na visualização "My Responses" do usuário e não são expostas aos receptores de webhook.

Resultados de questionário

Para formulários em modo de questionário (knowledge_quiz, lead_qualification ou match_quiz), a resposta armazenada inclui um objeto quizResults. Embora esse objeto não seja incluído diretamente no payload do webhook, você pode obtê-lo pela API de Respostas usando o responseId do webhook.

O objeto quizResults tem a seguinte estrutura:

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

Metadados

A resposta armazenada também pode incluir um objeto metadata contendo campos ocultos passados via parâmetros de URL. Ele está disponível pela API de Respostas, mas não é incluído no payload do webhook.

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

Para acessar os metadados de uma resposta entregue via webhook, busque-a usando o responseId:

curl https://app.nueform.com/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

Cabeçalhos HTTP

Toda requisição de webhook inclui estes cabeçalhos HTTP:

Consulte Verificação para saber como validar a assinatura.

Tamanho do payload

Os payloads de webhook costumam ser pequenos (menos de 10 KB). O tamanho depende principalmente do número de perguntas e do comprimento das respostas de texto. Respostas de upload de arquivo contêm URLs (não o conteúdo dos arquivos), então não aumentam significativamente o tamanho do payload.

Próximos passos

• Verificação --- Valide assinaturas de webhook
• Testes --- Teste payloads de webhook localmente
• Eventos --- Tipos de evento e garantias de entrega