Configurar e gerir Webhooks Padrão no Enquete

Os Webhooks Padrão permitem que o Enquete envie automaticamente informações relacionadas com inquéritos para outra aplicação quando ocorre um evento selecionado.

Por exemplo, quando um inquirido envia ou conclui um inquérito, o Enquete pode enviar os dados do evento diretamente para o seu sistema de gestão de relações com clientes, plataforma de relatórios, base de dados interna, aplicação de suporte, plataforma de marketing ou outro serviço externo.

Isto ajuda a sua organização a automatizar fluxos de trabalho e a transferir dados de inquéritos entre sistemas sem ter de exportar repetidamente as respostas ou transferir informações manualmente.

Este guia explica como criar, configurar, testar, monitorizar e gerir Webhooks Padrão através da interface do Enquete.

 

 

O que é um Webhook Padrão?

Um Webhook Padrão é uma ligação automatizada entre o Enquete e uma aplicação externa.

Quando ocorre um evento num inquérito selecionado, o Enquete envia um pedido HTTP POST para o URL do endpoint configurado na subscrição do webhook.

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

• Enviar novas respostas de inquéritos para um CRM.
• Armazenar dados de inquéritos numa base de dados interna.
• Notificar uma equipa de suporte ou de sucesso do cliente.
• Iniciar um fluxo de trabalho de relatórios ou análise.
• Criar ou atualizar um registo noutra aplicação.
• Acionar um processo empresarial interno personalizado.

Cada Webhook Padrão está associado a um inquérito e a um tipo de evento específicos. Isto permite controlar quais as atividades que 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 a sua equipa técnica preparou:

• Um endpoint HTTPS acessível publicamente.
• Um servidor capaz de receber pedidos HTTP POST.
• Um processo para ler corpos de pedidos JSON.
• Uma localização segura para armazenar o segredo do webhook.
• Um processo para verificar assinaturas de webhook.
• Um método para impedir o processamento duplicado de eventos.

O endpoint recetor deve responder rapidamente depois de aceitar um pedido. As operações demoradas devem normalmente ser enviadas para uma fila ou para um sistema de processamento em segundo plano depois de o endpoint devolver uma resposta bem-sucedida.

Os programadores devem consultar a Documentação oficial de Webhooks antes de implementarem o endpoint recetor.

 

Como abrir os Webhooks Padrão

Passo 1: Abra as Integrações

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

 

Passo 2: Selecione Webhooks Padrão

Abra Webhooks Padrão a partir das opções de integração disponíveis.

A visão geral dos Webhooks Padrão apresenta todas as subscrições de webhook disponíveis na sua conta.

Nesta página, pode:

• Criar um novo webhook.
• Ver subscrições de webhook existentes.
• Editar as definições de webhook.
• Revelar e copiar segredos de webhook.
• Enviar entregas de teste.
• Consultar os registos de entrega.
• Ativar ou desativar um webhook.
• Eliminar um webhook.

 

Como criar um Webhook Padrão

Passo 1: Clique em Adicionar webhook

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

Será aberto um formulário de configuração.

Passo 2: Introduza o URL do endpoint

Introduza 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 estar acessível publicamente e conseguir aceitar pedidos HTTP POST.

Endereços localhost, URLs privadas de desenvolvimento e páginas que exijam um início de sessão interativo não podem receber entregas de webhook do Enquete.

Passo 3: Adicione uma descrição

Introduza 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 posterior do webhook, especialmente quando a sua organização gere várias subscrições.

Passo 4: Selecione um inquérito

Selecione o inquérito cujos eventos devem acionar o webhook.

Uma subscrição de Webhook Padrão está associada a um único inquérito. Se precisar de enviar eventos de vários inquéritos, crie uma subscrição de webhook separada para cada inquérito.

Passo 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 das funcionalidades ativadas na sua conta.

Passo 6: Escolha o estado de ativação

Escolha se o webhook deve ficar ativo imediatamente.

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

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

Pode manter um webhook inativo enquanto a sua equipa técnica termina de preparar ou testar o endpoint recetor.

Passo 7: Guarde o webhook

Clique em Guardar para criar a subscrição do webhook.

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

 

Como gerir o segredo do webhook

Cada Webhook Padrão possui um segredo. A aplicação recetora utiliza este segredo para verificar se um pedido recebido veio realmente do Enquete.

O segredo do webhook deve ser tratado como uma palavra-passe ou uma credencial privada de API.

 

Passo 1: Revele o segredo

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

O segredo será apresentado temporariamente.

Passo 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 ficar automaticamente oculto após aproximadamente dez segundos.

Passo 3: Armazene o segredo em segurança

Entregue o segredo ao programador responsável pelo endpoint recetor e armazene-o numa localização segura do lado do servidor, como:

• Uma variável de ambiente.
• Uma configuração de aplicação encriptada.
• Um gestor de segredos na nuvem.
• Um repositório protegido de credenciais.

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

 

Como testar um webhook

Deve testar todos os webhooks antes de os utilizar num fluxo de trabalho em produção.

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

Passo 1: Localize o webhook

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

Passo 2: Envie uma entrega de teste

Clique no ícone do relâmpago na linha do webhook.

O Enquete enviará um pedido de teste para o endpoint configurado.

Passo 3: Analise o resultado

Uma notificação incorporada apresentará o estado HTTP devolvido pelo endpoint.

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

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

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

 

Como editar um webhook

Pode atualizar um webhook existente quando o respetivo endpoint, inquérito, tipo de evento, descrição ou estado de ativação for alterado.

Passo 1: Clique em Editar

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

Passo 2: Atualize as definições

Pode atualizar definições como:

• O URL do endpoint.
• A descrição do webhook.
• O inquérito selecionado.
• O tipo de evento.
• O estado ativo ou inativo.

Passo 3: Guarde as alterações

Guarde o webhook depois de efetuar as alterações.

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

Envie sempre uma nova entrega de teste depois de alterar o URL do endpoint, o inquérito ou o tipo de evento.

 

Como consultar os registos de entrega

Os registos de entrega apresentam os pedidos que o Enquete enviou para o seu endpoint e as respostas devolvidas pelo servidor recetor.

Utilize estes registos para monitorizar o estado da sua integração e investigar entregas falhadas.

Passo 1: Abra os registos

Localize a subscrição do webhook e clique no ícone Ver registos junto ao botão de eliminação.

Passo 2: Filtre o histórico de entregas

Pode filtrar as entregas por:

• Todas
• Bem-sucedidas
• Falhadas

Passo 3: Analise uma entrega

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

O registo da entrega pode incluir:

• O payload do pedido.
• O estado da resposta HTTP.
• O corpo da resposta devolvida pelo servidor recetor.
• Uma mensagem de erro.
• A duração da entrega em milissegundos.
• O número da tentativa de entrega.
• O identificador único da entrega.

Os registos de entrega são particularmente úteis depois de:

• Criar um novo webhook.
• Alterar o URL de um endpoint.
• Implementar uma atualização na aplicação recetora.
• Alterar as definições da firewall ou do servidor.
• Investigar dados de inquéritos em falta.
• Investigar entregas lentas ou falhadas.

 

Compreender os cabeçalhos dos webhooks

Cada pedido de webhook contém cabeçalhos que ajudam a aplicação recetora a identificar, verificar e acompanhar a entrega.

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

A sua equipa técnica deve utilizar o cabeçalho de assinatura para autenticar os pedidos recebidos e o cabeçalho de entrega para impedir que o mesmo evento seja processado mais do que uma vez.

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

 

Compreender as entregas duplicadas

Uma entrega de webhook pode ser tentada mais do que uma vez se o primeiro pedido falhar, exceder o tempo limite ou não devolver uma resposta bem-sucedida.

Isto significa que a aplicação recetora deve ser capaz de reconhecer e ignorar em segurança uma entrega que já tenha sido processada.

Cada pedido inclui um valor único no cabeçalho X-Enquete-Delivery.

A sua equipa técnica deve utilizar este valor como chave de idempotência.

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

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

Os identificadores de entregas processadas devem ser mantidos durante 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 pretender interromper temporariamente as entregas sem eliminar a respetiva configuração.

Pode desativar um webhook enquanto:

• A aplicação recetora está em manutenção.
• A sua equipa técnica está a substituir o endpoint.
• O fluxo de trabalho associado está temporariamente em pausa.
• Está a investigar falhas repetidas.
• O webhook não é atualmente necessário.

Quando o webhook for novamente ativado, os eventos futuros correspondentes poderão ser entregues.

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

 

Como eliminar um webhook

Elimine um webhook quando a subscrição já não for necessária.

Passo 1: Selecione Eliminar

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

Passo 2: Confirme a eliminação

Confirme que pretende remover permanentemente a subscrição do webhook.

Após a eliminação, o Enquete deixará de enviar novas entregas para esse webhook.

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

Importante: Se pretender apenas colocar o webhook temporariamente em pausa, desative-o em vez de o eliminar.

 

Resolução de problemas com Webhooks Padrão

A entrega do webhook falha ou excede o tempo limite

Verifique o seguinte:

• Confirme que o endpoint está acessível publicamente.
• Confirme que o endpoint utiliza HTTPS.
• Verifique se uma firewall ou uma regra de segurança está a bloquear o pedido.
• Confirme que o endpoint aceita pedidos HTTP POST.
• Certifique-se de que o servidor recetor responde rapidamente.
• Consulte os registos de entrega para verificar o estado da resposta e a mensagem de erro.
• Confirme que a aplicação recetora está atualmente disponível.

As tarefas demoradas devem ser colocadas numa fila para processamento em segundo plano, em vez de serem concluídas antes de o servidor devolver a resposta.

A assinatura do webhook é inválida

Peça à sua equipa técnica para confirmar que:

• O segredo pertence à subscrição de webhook correta.
• O corpo original do pedido está a ser utilizado para verificar a assinatura.
• O corpo JSON não é reformatado antes de ser verificado.
• 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 de verificação atuais.

Não são recebidas entregas de webhook

Verifique o seguinte:

• Certifique-se de que o webhook está ativo.
• Confirme que foi selecionado o inquérito correto.
• Confirme que o evento selecionado ocorreu realmente.
• Verifique se o URL do endpoint está correto.
• Envie uma entrega de teste.
• Abra os registos de entrega para confirmar se foi efetuada uma tentativa de pedido.

O endpoint devolve uma resposta 401 ou 403

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

Verifique se:

• O endpoint exige um método de autenticação não suportado.
• Uma firewall ou gateway de API está a rejeitar o pedido.
• O endpoint aceita apenas pedidos provenientes de redes selecionadas.
• O processo de verificação da assinatura está a rejeitar incorretamente pedidos válidos.

O endpoint devolve uma resposta 404

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

Verifique o URL completo e confirme que a rota existe e aceita pedidos HTTP POST.

O endpoint devolve uma resposta 500

Uma resposta 500 indica que ocorreu um erro dentro da aplicação recetora.

A sua equipa técnica deve consultar os registos do servidor da aplicação recetora juntamente com o payload da entrega e o identificador da entrega apresentados no Enquete.

O mesmo evento é processado mais do que uma vez

Os pedidos de webhook podem ser repetidos após falhas ou excederem o tempo limite.

A sua equipa 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

• Utilize sempre um endpoint HTTPS.
• Verifique a assinatura do webhook antes de processar um pedido.
• Armazene o segredo do webhook apenas em sistemas seguros do lado do servidor.
• Nunca exponha o segredo no código do frontend.
• Utilize o corpo original do pedido durante a verificação da assinatura.
• Utilize o identificador da entrega para impedir o processamento duplicado.
• Devolva rapidamente uma resposta bem-sucedida.
• Processe as operações demoradas de forma assíncrona.
• Monitorize entregas falhadas e respostas invulgarmente lentas.
• Consulte os registos de entrega depois de implementar atualizações no endpoint.
• Teste o webhook depois de cada alteração de configuração.
• Desative subscrições de webhook que não estejam temporariamente a ser utilizadas.
• Elimine subscrições que já não sejam necessárias.

 

Lista de verificação antes de ativar um webhook

Antes de utilizar um Webhook Padrão num fluxo de trabalho em produção, confirme que concluiu os seguintes passos:

1. Crie o webhook utilizando o endpoint HTTPS correto.
2. Selecione o inquérito correto.
3. Selecione o tipo de evento correto.
4. Copie e armazene em segurança o segredo do webhook.
5. Implemente a verificação da assinatura no servidor recetor.
6. Implemente proteção contra entregas duplicadas.
7. Envie uma entrega de teste.
8. Confirme que o endpoint devolve uma resposta bem-sucedida.
9. Consulte os detalhes do pedido e da resposta nos registos de entrega.
10. Configure a monitorização e os alertas de falha para o endpoint recetor.
11. Ative o webhook para eventos de inquéritos em produção.

Depois de o webhook entrar em funcionamento, consulte regularmente as entregas falhadas e o desempenho do endpoint para garantir que a integração continua a funcionar 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 programadores, consulte sempre a Documentação oficial de Webhooks do Enquete.