Webhooks

Configure notificações de eventos em tempo real

Webhooks

Um webhook é a entrega de dados a um endpoint quando um evento ocorre. No nosso caso, esse evento é o envio de uma resposta a uma pesquisa. Os webhooks são destinados a usuários avançados com conhecimento de programação.

Como conectar

Para configurar webhooks, acesse a aba Integrações → Webhooks e clique em Conectar.

Baixe a versão em markdown da seção "Webhooks" para usar no ChatGPT ou outros LLMs:

Interface de configuração de webhooks

Passo 1: Acessar integrações

Para configurar webhooks, acesse a aba Integrações → Webhooks e clique em Conectar.

Passo 2: Formulário de configuração do webhook

Uma tela será aberta onde você deverá inserir o nome do webhook, a URL de callback e o tipo de requisição.

Passo 3: Testar o webhook

Você pode testar o webhook usando https://webhook.site

Passo 4: Visualizar registros

Ou visualizando os registros na interface do SurveyNinja.

Configurações do webhook

O formulário de configuração do webhook possui os seguintes parâmetros:

Parâmetro Descrição
Nome Um nome personalizado para identificar o webhook na lista
URL A URL do seu endpoint. O SurveyNinja envia uma requisição POST para ela a cada nova resposta de pesquisa
Cabeçalhos Cabeçalhos HTTP personalizados no formato "chave: valor". Enviados com cada requisição e duplicados no campo headers do corpo do payload para facilitar o registro
Habilitado Alternância de atividade. Um webhook desabilitado não envia requisições, mas mantém todas as configurações

Token secreto via cabeçalho

Adicione um cabeçalho Authorization: Bearer seu-segredo — seu servidor poderá verificar que a requisição veio genuinamente do SurveyNinja.

Quando os webhooks são disparados

No SurveyNinja, os webhooks são disparados quando uma resposta de pesquisa é enviada. Este é o principal evento que você pode rastrear.

Evento: Resposta de pesquisa

O webhook é disparado toda vez que um respondente envia uma resposta à sua pesquisa, fornecendo notificações em tempo real de novas respostas.

Entrega automática

O webhook é enviado automaticamente assim que uma resposta de pesquisa é recebida

Formato do payload

O SurveyNinja envia uma requisição POST com um corpo JSON. A estrutura completa do corpo da requisição está descrita abaixo.

Campos raiz do payload

Campo Tipo Descrição
headers object Cabeçalhos configurados no webhook. Duplicados no corpo para facilitar o registro e a depuração
extra_params object / array Variáveis ocultas e tags UTM enviadas durante a pesquisa. Array vazio [] se não houver variáveis
promo_code string / null Código promocional usado durante a pesquisa, ou null
log_id int ID do registro de entrega deste webhook
score_all int Pontuação máxima possível para toda a pesquisa. 0 se a pontuação não estiver configurada
score_earned int Pontuação total obtida pelo respondente
score_percent float / null Percentual do resultado: (score_earned / score_all) × 100, arredondado para 1 casa decimal. null se score_all = 0
scores object Resumo de pontuação: campos user, max e by_question — um mapa { "uuid": int | null }
{question_uuid} object Resposta à pergunta com este UUID. Cada pergunta da pesquisa tem uma chave de nível superior separada

Campos do objeto de pergunta

Cada pergunta no payload é um objeto identificado pelo UUID da pergunta. Todos os tipos de perguntas compartilham os seguintes campos comuns:

Campo Tipo Descrição
title string Texto da pergunta (título do widget)
type string Tipo de widget: choiceSingle, choiceMultiple, rating, matrix e outros.
question_uuid / uuid string UUID da pergunta (duplicado dentro do objeto)
results object / array Resposta do respondente. O formato depende do tipo de widget — veja a seção abaixo
score_count int / null Pontuação obtida para esta pergunta. null se a pontuação não se aplica a este tipo
score_max int / null Pontuação máxima para esta pergunta. null se a pontuação não se aplica
is_correct_question bool / null Correção geral da resposta: true — correta, false — incorreta, null — não aplicável
other string Texto da opção 'Outro', se selecionada (para widgets de escolha). String vazia se não selecionada
inline_group_id string / null UUID do grupo de perguntas, se a pergunta pertencer a um grupo
inline_group_title string / null Nome do grupo de perguntas
is_inline_group_child bool true se a pergunta estiver dentro de um grupo

Formato de results por tipo de widget

O campo results tem um formato diferente dependendo do tipo de pergunta.

choiceSingle, choiceMultiple, yesno, dropdown

Array de opções selecionadas. Cada elemento contém o texto da opção, a pontuação e o indicador de correção.

{
  "results": [
    {
      "result": "Option A",
      "score": 10,
      "is_correct": true
    }
  ]
}

choiceMedia

Array de opções de mídia selecionadas. O campo result contém a URL da imagem da opção selecionada.

{
  "results": [
    {
      "result": "https://app.surveyninja.io/.../image.png",
      "score": 3,
      "is_correct": false
    }
  ]
}

ranking

Array de opções na ordem definida pelo usuário (primeiro elemento = classificado em 1.°). Pontuação e correção não se aplicam a este tipo.

{
  "results": [
    { "result": "First place",  "score": null, "is_correct": null },
    { "result": "Second place", "score": null, "is_correct": null },
    { "result": "Third place",  "score": null, "is_correct": null }
  ]
}

rating

Objeto (não array). Campo is_star: true — modo de estrelas/corações; score_num: false — modo de exibição não numérica.

{
  "results": {
    "result": "4",
    "is_star": true,
    "score": 0,
    "score_num": false,
    "is_correct": false
  }
}

scale

Objeto com o valor de escala selecionado, a pontuação e a correção.

{
  "results": {
    "result": "6",
    "score": 0,
    "is_correct": true
  }
}

slider

Objeto apenas com o valor. A pontuação não se aplica a sliders.

{
  "results": {
    "result": "45"
  }
}

input, email, phone

Objeto com o valor inserido. A pontuação não se aplica. Para entradas multilinha, as quebras de linha são preservadas.

{
  "results": {
    "result": "User's answer text"
  }
}

datetime

Objeto com um valor de data/hora. O formato do valor depende do modo do widget.

// Date + time
{ "results": { "result": "12.03.2026 21:12" } }

// Date only
{ "results": { "result": "11.03.2026" } }

// Time only
{ "results": { "result": "18:14" } }

file

Array de arquivos enviados. Cada elemento contém uma URL de download e a extensão do arquivo.

{
  "results": [
    {
      "result": "https://app.surveyninja.io/.../document.pdf",
      "file_ext": "pdf"
    }
  ]
}

matrix

O tipo mais complexo. Contém duas representações: results — visão legível por humanos: objeto aninhado { "linha": { "coluna": { result, score, is_correct } } }. Valor result: "1" — célula marcada, result: "" — vazia. answers — visão por UUID para máquinas: { "row_uuid": { "col_uuid": true | false } }

{
  "results": {
    "Pasta": {
      "Bad":  { "result": "1", "score": 2,    "is_correct": false },
      "OK":   { "result": "",  "score": null,  "is_correct": false },
      "Good": { "result": "",  "score": null,  "is_correct": true  }
    },
    "Potatoes": {
      "Bad":  { "result": "1", "score": 2,    "is_correct": true  },
      "OK":   { "result": "",  "score": null,  "is_correct": true  },
      "Good": { "result": "",  "score": null,  "is_correct": false }
    }
  },
  "answers": {
    "row-uuid-1": { "col-uuid-1": true, "col-uuid-2": false, "col-uuid-3": false },
    "row-uuid-2": { "col-uuid-1": true, "col-uuid-2": false, "col-uuid-3": false }
  },
  "is_bool": true
}

Exemplo completo do payload

Um exemplo real do corpo de uma requisição webhook com pontuação, múltiplos tipos de perguntas e cabeçalhos personalizados. Os UUIDs foram abreviados para facilitar a leitura.

{
  "headers": {
    "Authorization": "Bearer my-secret-token",
    "X-Source": "surveyninja"
  },
  "extra_params": { "utm_source": "email", "utm_campaign": "spring2024" },
  "promo_code": null,
  "log_id": 1916713,
  "score_all": 52,
  "score_earned": 29,
  "score_percent": 55.8,
  "scores": {
    "user": 29,
    "max": 52,
    "by_question": {
      "uuid-choice-1":  0,
      "uuid-choice-2":  3,
      "uuid-rating-1":  0,
      "uuid-scale-1":   0,
      "uuid-matrix-1":  6
    }
  },

  "uuid-choice-1": {
    "title": "Select one option",
    "type": "choiceSingle",
    "question_uuid": "uuid-choice-1",
    "uuid": "uuid-choice-1",
    "results": [
      { "result": "Option B", "score": 0, "is_correct": false }
    ],
    "score_count": 0,
    "score_max": 4,
    "is_correct_question": false,
    "other": "",
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-choice-2": {
    "title": "Check all that apply",
    "type": "choiceMultiple",
    "question_uuid": "uuid-choice-2",
    "uuid": "uuid-choice-2",
    "results": [
      { "result": "Option A", "score": 3, "is_correct": true }
    ],
    "score_count": 3,
    "score_max": 3,
    "is_correct_question": true,
    "other": "",
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-rating-1": {
    "title": "Rate the service",
    "type": "rating",
    "question_uuid": "uuid-rating-1",
    "uuid": "uuid-rating-1",
    "results": {
      "result": "4",
      "is_star": true,
      "score": 0,
      "score_num": false,
      "is_correct": false
    },
    "score_count": 0,
    "score_max": 2,
    "is_correct_question": false,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-scale-1": {
    "title": "On a scale of 1 to 10",
    "type": "scale",
    "question_uuid": "uuid-scale-1",
    "uuid": "uuid-scale-1",
    "results": {
      "result": "6",
      "score": 0,
      "is_correct": true
    },
    "score_count": 0,
    "score_max": 3,
    "is_correct_question": true,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-input-1": {
    "title": "Leave a comment",
    "type": "input",
    "question_uuid": "uuid-input-1",
    "uuid": "uuid-input-1",
    "results": { "result": "Everything is great!" },
    "score_count": null,
    "score_max": null,
    "is_correct_question": null,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-file-1": {
    "title": "Attach a file",
    "type": "file",
    "question_uuid": "uuid-file-1",
    "uuid": "uuid-file-1",
    "results": [
      {
        "result": "https://app.surveyninja.io/.../document.pdf",
        "file_ext": "pdf"
      }
    ],
    "score_count": null,
    "score_max": null,
    "is_correct_question": null,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-matrix-1": {
    "title": "Rate the dishes",
    "type": "matrix",
    "question_uuid": "uuid-matrix-1",
    "uuid": "uuid-matrix-1",
    "results": {
      "Pasta": {
        "Bad":  { "result": "1", "score": 2,   "is_correct": false },
        "Good": { "result": "",  "score": null, "is_correct": true  }
      },
      "Potatoes": {
        "Bad":  { "result": "1", "score": 2,   "is_correct": true  },
        "Good": { "result": "",  "score": null, "is_correct": false }
      }
    },
    "answers": {
      "row-uuid-1": { "col-uuid-1": true, "col-uuid-2": false },
      "row-uuid-2": { "col-uuid-1": true, "col-uuid-2": false }
    },
    "is_bool": true,
    "score_count": 6,
    "score_max": 6,
    "is_correct_question": false,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  }
}

Compatibilidade retroativa

Os campos de pontuação (score_max, is_correct_question, is_correct dentro de results) são adicionados sobre o formato base. Os campos existentes não são removidos nem renomeados.

Testar webhooks

Você pode usar as seguintes ferramentas para testar os webhooks:

webhook.site

Serviço recomendado para testar webhooks

https://webhook.site

Acesse o site, obtenha uma URL única e use-a para testar seus webhooks.

Visualizar registros

Você pode verificar o funcionamento do webhook pelos registros

A interface do SurveyNinja fornece registros de entrega de webhooks para rastrear seu funcionamento.

Segurança

Para a segurança dos webhooks, recomenda-se usar HTTPS e verificar a autenticidade das requisições.

Recomendações de segurança

  • Use HTTPS para a URL de callback
  • Verifique as assinaturas das requisições para confirmar sua autenticidade
  • Restrinja o acesso ao endpoint apenas aos endereços IP do SurveyNinja
  • Implemente tempos limite para o processamento de webhooks