Webhooks

Atualizado 21 de outubro de 2026

Disponível em

~~Grátis~~: não incluído
Básico
Padrão
Premium
Enterprise

Nesta página

Um webhook envia cada resposta completa da pesquisa para a URL que você indicar, como uma solicitação HTTP com corpo JSON. Use-o para passar as respostas para o seu CRM, para o seu backend ou para um serviço de automação.

Antes de começar

Você precisa de um servidor ou serviço que aceite solicitações HTTP em um endereço público. Para testar webhooks sem um servidor próprio, use um endpoint de teste de um serviço como o webhook.site.

Criar um webhook

Abra a pesquisa e vá para a aba Integrações.
Clique em Webhook na lista.
Clique em Criar webhook. Se a pesquisa já tiver webhooks, clique em Criar novo webhook.

Preencha os campos:

Campo	O que informar
Nome do webhook	Qualquer nome para diferenciar os webhooks, por exemplo "CRM"
URL de retorno (1)	O endereço que recebe as respostas. Precisa ser um endereço público: endereços internos e locais não são permitidos
Formato de dados	Sempre JSON
Tipo de solicitação (2)	POST, PUT, PATCH ou GET. A maioria dos serviços espera POST

Em Cabeçalho (3), adicione os cabeçalhos de que o seu servidor precisa, por exemplo um token de autorização: informe o Nome do cabeçalho e o Valor. Para adicionar mais um cabeçalho, clique em Adicionar linha.
Em Elementos (4), escolha as perguntas que serão enviadas. Por padrão, todas as perguntas e variáveis ocultas ficam selecionadas e destacadas. Clique em uma pergunta para excluí-la da solicitação e clique de novo para adicioná-la outra vez. As variáveis ocultas funcionam do mesmo jeito em Variáveis ocultas.
Em Nomes dos parâmetros, você pode dar nomes curtos às perguntas selecionadas. O nome é enviado no campo name da pergunta.
Clique em Salvar.

O novo webhook aparece desativado na Lista de webhooks. Ative o botão ao lado dele para começar a enviar respostas.

Conteúdo mostra os IDs dos elementos selecionados. No corpo da solicitação, as perguntas usam esses IDs como chaves, e as variáveis ocultas vão em extra_params.

Uma pesquisa pode ter vários webhooks. A Lista de webhooks mostra todos eles, e o menu de cada um tem Editar, Logs e Excluir.

Enviar respostas incompletas

Por padrão, o webhook recebe só respostas completas. Para receber também as que os respondentes começaram e não terminaram, ative Enviar respostas não finalizadas e escolha um intervalo em Enviar a cada: 1, 6, 12 ou 24 horas. Uma resposta incompleta que já foi entregue não é enviada de novo.

O corpo da solicitação não indica se a resposta está completa. Se o respondente terminar a pesquisa mais tarde, o webhook recebe a resposta de novo, agora como completa.

Formato da solicitação

O SurveyNinja envia a solicitação com o cabeçalho Content-Type: application/json e os cabeçalhos que você adicionou em Cabeçalho. O corpo contém campos gerais e um objeto para cada pergunta selecionada, com o ID da pergunta como chave.

Campo	Descrição
extra_params	Valores das variáveis ocultas selecionadas. As chaves são os nomes das variáveis em minúsculas. Valores vazios são ignorados; se não sobrar nenhum, extra_params é um array vazio []
headers	Os cabeçalhos personalizados das configurações do webhook
score_all, score_earned, score_percent	Pontuação máxima, pontuação do respondente e porcentagem, se a pesquisa usa pontuação
scores	As mesmas pontuações e o detalhamento por pergunta (by_question). by_question traz todas as perguntas respondidas, inclusive as que não foram selecionadas em Elementos
promo_code, order_number	O código promocional entregue ao respondente e o número do pedido, se a pesquisa os usa. Caso contrário, null
log_id	O ID do envio nos logs do webhook
ID da pergunta	O título, o tipo, as respostas (results) e os dados de pontuação da pergunta

Exemplo do corpo de uma solicitação para uma pesquisa com uma pergunta de escolha, uma pergunta de e-mail e uma variável oculta:

{
  "extra_params": {
    "utm_source": "newsletter"
  },
  "headers": {
    "X-Api-Key": "sua-chave-secreta"
  },
  "score_all": 0,
  "score_earned": 0,
  "score_percent": null,
  "scores": {
    "user": 0,
    "max": 0,
    "by_question": {
      "3ec8521a-3af8-4fec-b11e-7409d38eab33": null,
      "87a748c3-43e5-4ecc-bba2-413deb908864": null
    }
  },
  "promo_code": null,
  "order_number": null,
  "3ec8521a-3af8-4fec-b11e-7409d38eab33": {
    "title": "Como você conheceu a gente?",
    "results": [
      { "result": "Mecanismo de busca", "score": null, "is_correct": null }
    ],
    "score_count": null,
    "type": "choiceSingle",
    "other": "",
    "score_max": null,
    "is_correct_question": null,
    "uuid": "3ec8521a-3af8-4fec-b11e-7409d38eab33",
    "name": "source"
  },
  "87a748c3-43e5-4ecc-bba2-413deb908864": {
    "title": "Seu e-mail",
    "results": { "result": "anna@example.com" },
    "type": "email",
    "score_count": null,
    "score_max": null,
    "is_correct_question": null,
    "uuid": "87a748c3-43e5-4ecc-bba2-413deb908864"
  },
  "log_id": 1024
}

Nas perguntas de escolha, results é uma lista das opções escolhidas e other traz o texto da opção "Outro". Nas perguntas de texto, e-mail, número e similares, results é um único objeto com a resposta em result. O campo name só aparece nas perguntas que você nomeou em Nomes dos parâmetros. Em uma solicitação de teste, name traz o título de cada pergunta. Decodifique as entidades HTML de name do seu lado, por exemplo & para &.

Conferir os envios nos logs

Na Lista de webhooks, abra o menu do webhook e escolha Logs.
Clique em Solicitação de teste (1) para enviar uma solicitação com respostas de teste para todas as perguntas. Ela é enviada mesmo com o webhook desativado.
Clique em um registro do log (3) para ver a resposta do servidor, o corpo da solicitação e os cabeçalhos.

Os contadores no topo mostram os envios Total, Com erro (2) e Na fila. Para enviar de novo uma solicitação com falha, abra-a e clique em Tentar novamente. Quando o log tem mais de uma solicitação com falha, aparece o bloco Reenviar logs com falha: defina as datas e clique em Tentar novamente para reenviar todas as solicitações com falha desse período, até 1.000 de cada vez. Tentar novamente reenvia o corpo e os cabeçalhos salvos para a URL de retorno atual, mesmo que o webhook esteja desativado.

Desativar ou excluir um webhook

Para pausar o envio, desative o botão do webhook na Lista de webhooks. Para remover o webhook, abra o menu dele e escolha Excluir. O webhook e o log dele são excluídos na hora, sem confirmação.

Limites

A URL de retorno precisa ser um endereço público http ou https, e o domínio precisa ser resolvido quando você salva o webhook. Endereços internos e locais não são permitidos.
Os nomes dos cabeçalhos só podem ter letras latinas, dígitos e os caracteres ! # $ % & ' * + - . ^ _ ` | ~. Cabeçalhos com outros nomes não são enviados.
As respostas recebidas enquanto o webhook está desativado não são enviadas depois.
Nomes dos parâmetros funciona só para perguntas. Os nomes dados às variáveis ocultas não são usados.
O corpo da solicitação é sempre JSON.
O envio é considerado bem-sucedido se o seu servidor responder com qualquer código 2xx. O SurveyNinja espera a resposta por até 30 segundos e segue redirecionamentos.
Um envio com falha não é repetido automaticamente. Ele fica no log com o erro, e você pode enviá-lo de novo a partir do log.
Se um webhook falhar 20 vezes seguidas, ou 5 vezes seguidas com uma resposta 4xx, o SurveyNinja o desativa e envia um e-mail ao autor da pesquisa, se as Notificações do sistema estiverem ativadas no perfil dele.

Se algo não funcionar

As respostas não chegam. Um webhook novo é salvo desativado. Ative o botão dele na Lista de webhooks.
"Endpoint desativado automaticamente." O webhook falhou várias vezes seguidas. Veja os erros no log, corrija o receptor e clique em Ativar novamente. Depois, reenvie as solicitações com falha a partir do log.
O webhook não é salvo. A URL de retorno não é um endereço válido, o domínio não é resolvido ou aponta para um endereço interno ou local. Use um endereço público http ou https.
"O endereço do endpoint não é permitido — verifique as configurações" no log. O endereço agora aponta para um endereço interno ou local, então o reenvio foi bloqueado. Altere a URL de retorno.
Tentar novamente falha com o mesmo erro depois que você mudou os cabeçalhos. Tentar novamente envia os cabeçalhos salvos com a solicitação original. Clique em Solicitação de teste para conferir as novas configurações. As novas respostas são enviadas com os novos cabeçalhos.
"O servidor não respondeu em 30 segundos." O seu servidor demora demais para responder. Faça com que ele devolva primeiro um código 2xx e processe os dados depois.
O log mostra o código 405. O servidor não aceita esse tipo de solicitação. Confira Tipo de solicitação: a maioria dos serviços espera POST.