Configurar e gerenciar Webhooks Padrão no Enquete

Os Webhooks Padrão permitem que o Enquete envie automaticamente informações relacionadas a pesquisas para outro aplicativo quando um evento selecionado ocorre.

Por exemplo, quando um respondente envia ou conclui uma pesquisa, o Enquete pode enviar os dados do evento diretamente para o seu sistema de gestão de relacionamento com o cliente, plataforma de relatórios, banco de dados interno, aplicativo de suporte, plataforma de marketing ou outro serviço externo.

Isso ajuda sua organização a automatizar fluxos de trabalho e transferir dados de pesquisas entre sistemas sem precisar exportar respostas repetidamente ou transferir informações manualmente.

Este guia explica como criar, configurar, testar, monitorar e gerenciar Webhooks Padrão pela interface do Enquete.

 

 

O que é um Webhook Padrão?

Um Webhook Padrão é uma conexão automatizada entre o Enquete e um aplicativo externo.

Quando um evento ocorre em uma pesquisa selecionada, o Enquete envia uma solicitação HTTP POST para a URL do endpoint configurada na assinatura do webhook.

Dependendo do fluxo de trabalho da sua organização, um webhook pode ser usado para:

• Enviar novas respostas de pesquisas para um CRM.
• Armazenar dados de pesquisas em um banco de dados interno.
• Notificar uma equipe de suporte ou de sucesso do cliente.
• Iniciar um fluxo de trabalho de relatórios ou análises.
• Criar ou atualizar um registro em outro aplicativo.
• Acionar um processo interno de negócios personalizado.

Cada Webhook Padrão está vinculado a uma pesquisa e a um tipo de evento específicos. Isso permite controlar quais atividades acionam uma entrega e para onde as informações são enviadas.

 

Antes de criar um webhook

Antes de configurar um Webhook Padrão, certifique-se de que sua equipe técnica tenha preparado:

• Um endpoint HTTPS acessível publicamente.
• Um servidor capaz de receber solicitações HTTP POST.
• Um processo para ler corpos de solicitações JSON.
• Um local seguro para armazenar o segredo do webhook.
• Um processo para verificar assinaturas de webhook.
• Um método para evitar o processamento duplicado de eventos.

O endpoint receptor deve responder rapidamente depois de aceitar uma solicitação. Operações demoradas normalmente devem ser encaminhadas para uma fila ou para um sistema de processamento em segundo plano depois que o endpoint retornar uma resposta bem-sucedida.

Os desenvolvedores devem consultar a Documentação oficial de Webhooks antes de implementar o endpoint receptor.

 

Como abrir os Webhooks Padrão

Etapa 1: Abra Integrações

No painel do Enquete, selecione Integrações no menu superior.

 

Etapa 2: Selecione Webhooks Padrão

Abra Webhooks Padrão entre as opções de integração disponíveis.

A visão geral dos Webhooks Padrão exibe todas as assinaturas de webhook disponíveis na sua conta.

Nesta página, você pode:

• Criar um novo webhook.
• Visualizar assinaturas de webhook existentes.
• Editar as configurações dos webhooks.
• Exibir e copiar os segredos dos webhooks.
• Enviar entregas de teste.
• Consultar os registros de entrega.
• Ativar ou desativar um webhook.
• Excluir um webhook.

 

Como criar um Webhook Padrão

Etapa 1: Clique em Adicionar webhook

Na visão geral dos Webhooks Padrão, clique em Adicionar webhook.

Um formulário de configuração será aberto.

Etapa 2: Insira a URL do endpoint

Insira o endpoint HTTPS para o qual o Enquete deve enviar as entregas do webhook.

Por exemplo:

https://example.com/api/enquete/webhook

O endpoint deve ser acessível publicamente e capaz de aceitar solicitações HTTP POST.

Endereços localhost, URLs privadas de desenvolvimento e páginas que exigem login interativo não podem receber entregas de webhook do Enquete.

Etapa 3: Adicione uma descrição

Insira uma descrição que explique claramente a finalidade do webhook.

Por exemplo:

Enviar respostas concluídas de satisfação do cliente para o nosso CRM

Uma descrição clara facilita a identificação do webhook posteriormente, especialmente quando sua organização gerencia várias assinaturas.

Etapa 4: Selecione uma pesquisa

Selecione a pesquisa cujos eventos devem acionar o webhook.

Uma assinatura de Webhook Padrão está vinculada a uma única pesquisa. Se você precisar enviar eventos de várias pesquisas, crie uma assinatura de webhook separada para cada pesquisa.

Etapa 5: Selecione um tipo de evento

Selecione o evento que deve acionar a entrega do webhook.

Os eventos disponíveis na interface de Webhooks Padrão podem incluir:

• survey.new.response
• survey.response.completed

Os eventos disponíveis podem depender da configuração atual do Enquete e dos recursos habilitados na sua conta.

Etapa 6: Escolha o status de ativação

Escolha se o webhook deve ficar ativo imediatamente.

Quando um webhook está ativo, o Enquete envia entregas sempre que o evento selecionado ocorre.

Quando está inativo, a configuração continua disponível, mas as entregas de eventos em tempo real ficam pausadas.

Você pode manter um webhook inativo enquanto sua equipe técnica termina de preparar ou testar o endpoint receptor.

Etapa 7: Salve o webhook

Clique em Salvar para criar a assinatura do webhook.

O novo webhook aparecerá na visão geral dos Webhooks Padrão e poderá ser testado imediatamente.

 

Como gerenciar o segredo do webhook

Cada Webhook Padrão possui um segredo. O aplicativo receptor utiliza esse segredo para verificar se uma solicitação recebida realmente veio do Enquete.

O segredo do webhook deve ser tratado como uma senha ou uma credencial privada de API.

 

Etapa 1: Exiba o segredo

Localize o webhook na visão geral e clique no ícone de olho.

O segredo será exibido temporariamente.

Etapa 2: Copie o segredo

Clique no ícone da área de transferência para copiar o segredo.

Por motivos de segurança, o segredo volta a ser ocultado automaticamente depois de aproximadamente dez segundos.

Etapa 3: Armazene o segredo com segurança

Entregue o segredo ao desenvolvedor responsável pelo endpoint receptor e armazene-o em um local seguro no lado do servidor, como:

• Uma variável de ambiente.
• Uma configuração de aplicativo criptografada.
• Um gerenciador de segredos na nuvem.
• Um armazenamento protegido de credenciais.

Não armazene o segredo em JavaScript do frontend, repositórios públicos, capturas de tela, documentos compartilhados ou mensagens de suporte acessíveis a usuários não autorizados.

 

Como testar um webhook

Você deve testar todos os webhooks antes de utilizá-los em um fluxo de trabalho em produção.

Uma entrega de teste confirma que o endpoint está acessível e que o servidor receptor retorna uma resposta adequada.

Etapa 1: Localize o webhook

Encontre a assinatura do webhook na visão geral dos Webhooks Padrão.

Etapa 2: Envie uma entrega de teste

Clique no ícone de raio na linha do webhook.

O Enquete enviará uma solicitação de teste para o endpoint configurado.

Etapa 3: Analise o resultado

Uma notificação integrada exibirá o status HTTP retornado pelo endpoint.

Uma entrega bem-sucedida normalmente retorna um código de status entre 200 e 299, como:

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content

Se o teste falhar, abra os registros de entrega para analisar o status da resposta, o corpo da resposta, as informações do erro e a duração da solicitação.

 

Como editar um webhook

Você pode atualizar um webhook existente quando o endpoint, a pesquisa, o tipo de evento, a descrição ou o status de ativação forem alterados.

Etapa 1: Clique em Editar

Localize o webhook e selecione a ação Editar.

Etapa 2: Atualize as configurações

Você pode atualizar configurações como:

• A URL do endpoint.
• A descrição do webhook.
• A pesquisa selecionada.
• O tipo de evento.
• O status ativo ou inativo.

Etapa 3: Salve as alterações

Salve o webhook depois de fazer as alterações.

A configuração atualizada será utilizada nas entregas futuras.

Sempre envie outra entrega de teste depois de alterar a URL do endpoint, a pesquisa ou o tipo de evento.

 

Como visualizar os registros de entrega

Os registros de entrega mostram as solicitações que o Enquete enviou para o seu endpoint e as respostas retornadas pelo servidor receptor.

Use esses registros para monitorar o funcionamento da sua integração e investigar entregas com falha.

Etapa 1: Abra os registros

Localize a assinatura do webhook e clique no ícone Visualizar registros ao lado do botão de exclusão.

Etapa 2: Filtre o histórico de entregas

Você pode filtrar as entregas por:

• Todas
• Bem-sucedidas
• Com falha

Etapa 3: Analise uma entrega

Expanda uma entrada de entrega para consultar as informações de diagnóstico disponíveis.

O registro da entrega pode incluir:

• O payload da solicitação.
• O status da resposta HTTP.
• O corpo da resposta retornado pelo servidor receptor.
• Uma mensagem de erro.
• A duração da entrega em milissegundos.
• O número da tentativa de entrega.
• O identificador exclusivo da entrega.

Os registros de entrega são especialmente úteis depois de:

• Criar um novo webhook.
• Alterar a URL de um endpoint.
• Implantar uma atualização no aplicativo receptor.
• Alterar as configurações do firewall ou do servidor.
• Investigar dados de pesquisas ausentes.
• Investigar entregas lentas ou com falha.

 

Entendendo os cabeçalhos dos webhooks

Cada solicitação de webhook contém cabeçalhos que ajudam o aplicativo receptor a identificar, verificar e rastrear a entrega.

Cabeçalho	Descrição
X-Enquete-Signature	Contém a assinatura utilizada para verificar se a solicitação veio do Enquete.
X-Enquete-Event	Identifica o tipo de evento que acionou a entrega.
X-Enquete-Delivery	Contém um identificador exclusivo de entrega utilizado para rastreamento e prevenção de duplicidades.

Sua equipe técnica deve utilizar o cabeçalho de assinatura para autenticar as solicitações recebidas e o cabeçalho de entrega para impedir que o mesmo evento seja processado mais de uma vez.

Para consultar o formato exato da assinatura, o esquema do payload e exemplos de implementação, consulte a Documentação oficial de Webhooks.

 

Entendendo entregas duplicadas

Uma entrega de webhook pode ser tentada mais de uma vez se a primeira solicitação falhar, exceder o tempo limite ou não retornar uma resposta bem-sucedida.

Isso significa que o aplicativo receptor deve ser capaz de reconhecer e ignorar com segurança uma entrega que já tenha sido processada.

Cada solicitação inclui um valor exclusivo no cabeçalho X-Enquete-Delivery.

Sua equipe técnica deve utilizar esse valor como chave de idempotência.

Um processo típico de prevenção de duplicidades é:

1. Ler o valor de X-Enquete-Delivery.
2. Verificar se o identificador da entrega já foi processado.
3. Se já tiver sido processado, retornar uma resposta bem-sucedida sem repetir a ação.
4. Se ainda não tiver sido processado, armazenar o identificador da entrega e processar o evento.

Os identificadores de entregas processadas devem ser mantidos por um período adequado à política de integração e de novas tentativas da sua organização.

 

Como desativar um webhook

Desative um webhook quando quiser interromper temporariamente as entregas sem excluir sua configuração.

Você pode desativar um webhook enquanto:

• O aplicativo receptor estiver em manutenção.
• Sua equipe técnica estiver substituindo o endpoint.
• O fluxo de trabalho conectado estiver temporariamente pausado.
• Você estiver investigando falhas repetidas.
• O webhook não for necessário no momento.

Quando o webhook for ativado novamente, os próximos eventos correspondentes poderão ser entregues.

Os eventos que ocorrerem enquanto o webhook estiver inativo poderão não ser entregues automaticamente mais tarde.

 

Como excluir um webhook

Exclua um webhook quando a assinatura não for mais necessária.

Etapa 1: Selecione Excluir

Localize o webhook e clique na ação Excluir.

Etapa 2: Confirme a exclusão

Confirme que deseja remover permanentemente a assinatura do webhook.

Depois da exclusão, o Enquete não enviará mais novas entregas para esse webhook.

Os registros históricos de entrega podem continuar disponíveis nos registros do backend para fins de auditoria, solução de problemas ou operações.

Importante: Se você quiser apenas pausar temporariamente o webhook, desative-o em vez de excluí-lo.

 

Solução de problemas com Webhooks Padrão

A entrega do webhook falha ou excede o tempo limite

Verifique o seguinte:

• Confirme se o endpoint está acessível publicamente.
• Confirme se o endpoint utiliza HTTPS.
• Verifique se um firewall ou uma regra de segurança está bloqueando a solicitação.
• Confirme se o endpoint aceita solicitações HTTP POST.
• Certifique-se de que o servidor receptor responde rapidamente.
• Consulte os registros de entrega para verificar o status da resposta e a mensagem de erro.
• Confirme se o aplicativo receptor está disponível no momento.

Tarefas demoradas devem ser colocadas em uma fila para processamento em segundo plano, em vez de serem concluídas antes que o servidor retorne a resposta.

A assinatura do webhook é inválida

Peça à sua equipe técnica para confirmar se:

• O segredo pertence à assinatura de webhook correta.
• O corpo original da solicitação está sendo utilizado para verificar a assinatura.
• O corpo JSON não está sendo reformatado antes da verificação.
• O formato de assinatura esperado corresponde ao formato documentado pelo Enquete.

A verificação de assinaturas é uma tarefa técnica de implementação. Consulte a Documentação oficial de Webhooks para obter as instruções atuais de verificação.

Nenhuma entrega de webhook é recebida

Verifique o seguinte:

• Certifique-se de que o webhook está ativo.
• Confirme se a pesquisa correta foi selecionada.
• Confirme se o evento selecionado realmente ocorreu.
• Verifique se a URL do endpoint está correta.
• Envie uma entrega de teste.
• Abra os registros de entrega para confirmar se houve uma tentativa de solicitação.

O endpoint retorna uma resposta 401 ou 403

Uma resposta 401 ou 403 normalmente significa que o servidor receptor rejeitou a solicitação devido a uma regra de autenticação ou autorização.

Verifique se:

• O endpoint exige um método de autenticação não compatível.
• Um firewall ou gateway de API está rejeitando a solicitação.
• O endpoint aceita apenas solicitações de redes selecionadas.
• O processo de verificação da assinatura está rejeitando incorretamente solicitações válidas.

O endpoint retorna uma resposta 404

Uma resposta 404 normalmente significa que a URL do endpoint não corresponde a uma rota disponível no servidor receptor.

Verifique a URL completa e confirme se a rota existe e aceita solicitações HTTP POST.

O endpoint retorna uma resposta 500

Uma resposta 500 indica que ocorreu um erro dentro do aplicativo receptor.

Sua equipe técnica deve consultar os registros do servidor do aplicativo receptor juntamente com o payload da entrega e o identificador da entrega exibidos no Enquete.

O mesmo evento é processado mais de uma vez

As solicitações de webhook podem ser repetidas depois de falhas ou estouros do tempo limite.

Sua equipe técnica deve utilizar o valor X-Enquete-Delivery para identificar entregas que já tenham sido processadas.

 

Boas práticas de segurança para webhooks

• Sempre utilize um endpoint HTTPS.
• Verifique a assinatura do webhook antes de processar uma solicitação.
• Armazene o segredo do webhook apenas em sistemas seguros no lado do servidor.
• Nunca exponha o segredo no código do frontend.
• Utilize o corpo original da solicitação durante a verificação da assinatura.
• Utilize o identificador da entrega para evitar o processamento duplicado.
• Retorne rapidamente uma resposta bem-sucedida.
• Processe operações demoradas de forma assíncrona.
• Monitore entregas com falha e respostas anormalmente lentas.
• Consulte os registros de entrega depois de implantar atualizações no endpoint.
• Teste o webhook depois de cada alteração de configuração.
• Desative assinaturas de webhook que estejam temporariamente sem uso.
• Exclua assinaturas que não sejam mais necessárias.

 

Lista de verificação antes de ativar um webhook

Antes de utilizar um Webhook Padrão em um fluxo de trabalho em produção, confirme se você concluiu as etapas a seguir:

1. Crie o webhook usando o endpoint HTTPS correto.
2. Selecione a pesquisa correta.
3. Selecione o tipo de evento correto.
4. Copie e armazene com segurança o segredo do webhook.
5. Implemente a verificação da assinatura no servidor receptor.
6. Implemente proteção contra entregas duplicadas.
7. Envie uma entrega de teste.
8. Confirme se o endpoint retorna uma resposta bem-sucedida.
9. Consulte os detalhes da solicitação e da resposta nos registros de entrega.
10. Configure o monitoramento e os alertas de falha para o endpoint receptor.
11. Ative o webhook para eventos de pesquisas em produção.

Depois que o webhook entrar em funcionamento, consulte regularmente as entregas com falha e o desempenho do endpoint para garantir que a integração continue funcionando corretamente.

Para consultar os campos do payload, os esquemas de eventos, os exemplos de verificação de assinaturas e outras instruções específicas para desenvolvedores, consulte sempre a Documentação oficial de Webhooks do Enquete.