O NueForm envia notificações de webhook para eventos específicos que ocorrem na sua conta. Cada requisição de webhook inclui um campo event no payload JSON que identifica o que aconteceu.
Eventos atuais
form.submitted
Dispara quando um respondente envia uma resposta completa para um dos seus formulários.
| Propriedade | Valor |
|---|---|
| Nome do evento | form.submitted |
| Gatilho | Um respondente preenche e envia uma resposta de formulário |
| Payload | Detalhes do formulário, ID da resposta, respostas com timestamp |
| Formulários incrementais | Dispara apenas quando a resposta é marcada como complete |
Este é o principal evento de webhook do NueForm. Ele dispara tanto para formulários padrão (envio único) quanto para formulários de envio incremental, mas apenas quando a resposta atinge o estado de completa.
Quando dispara:
- Em um formulário padrão: imediatamente depois que o respondente clica em Enviar e a resposta é salva.
- Em um formulário incremental: apenas quando o envio final é feito com
complete: true. Salvamentos parciais não disparam este evento. - Em formulários no modo questionário (questionário de conhecimento, qualificação de leads, questionário de compatibilidade): o payload inclui os resultados de pontuação do questionário junto com as respostas.
Quando NÃO dispara:
- Envios parciais em formulários incrementais (em que
completenão étrue). - Edições em respostas existentes (respostas são imutáveis depois de enviadas).
- Rascunhos ou pré-visualizações de formulários.
- Envios de teste feitos na pré-visualização do construtor de formulários.
Consulte Payloads para o schema completo do payload.
Eventos futuros planejados
Os eventos a seguir estão planejados para versões futuras. Eles ainda não estão disponíveis, mas estão documentados aqui para que você possa projetar sua integração pensando em compatibilidade futura.
Os eventos futuros listados abaixo estão sujeitos a alterações. Confira o Registro de alterações para anúncios quando novos eventos ficarem disponíveis.
form.partial
Vai disparar quando uma resposta parcial for salva em um formulário com envio incremental ativado. Isso permitirá acompanhar o abandono de formulários e fazer follow-up com respondentes que começaram mas não terminaram.
| Propriedade | Valor planejado |
|---|---|
| Nome do evento | form.partial |
| Gatilho | Uma resposta parcial é criada ou atualizada (apenas formulários incrementais) |
| Payload | Mesma estrutura de form.submitted, com completedAt igual a null |
form.completed
Vai disparar quando uma resposta incremental passar de parcial para completa. Difere de form.submitted por indicar explicitamente que uma resposta antes parcial foi finalizada.
| Propriedade | Valor planejado |
|---|---|
| Nome do evento | form.completed |
| Gatilho | Uma resposta parcial é marcada como completa |
| Payload | Mesma estrutura de form.submitted, incluindo todas as respostas acumuladas |
form.published
Vai disparar quando um formulário for publicado ou republicado.
| Propriedade | Valor planejado |
|---|---|
| Nome do evento | form.published |
| Gatilho | Um formulário é publicado pelo painel ou pela API |
| Payload | ID do formulário, título, slug, número da versão, data/hora de publicação |
form.unpublished
Vai disparar quando um formulário for despublicado (tirado do ar).
| Propriedade | Valor planejado |
|---|---|
| Nome do evento | form.unpublished |
| Gatilho | Um formulário é despublicado pelo painel ou pela API |
| Payload | ID do formulário, título, slug, data/hora de despublicação |
Garantias de entrega de eventos
Entender como o NueForm entrega eventos de webhook é importante para construir integrações confiáveis.
Entrega no máximo uma vez
O NueForm atualmente oferece semântica de entrega no máximo uma vez (at-most-once). Cada evento é enviado uma única vez e não há nova tentativa se a entrega falhar. Isso significa que:
- Seu endpoint pode ocasionalmente perder eventos se estiver temporariamente indisponível.
- Você nunca receberá eventos duplicados para o mesmo envio a partir do sistema de entrega do NueForm.
- Projete sua integração para tolerar eventos perdidos.
Sem novas tentativas automáticas
Se o seu endpoint estiver inacessível, retornar um código de status de erro ou não responder dentro da janela de tempo limite de 5 segundos, a entrega do webhook é descartada silenciosamente. O NueForm não enfileira nem repete entregas que falharam.
Como não há novas tentativas automáticas, recomendamos fortemente complementar os webhooks com consultas periódicas à API de Respostas para capturar eventos que seu endpoint possa ter perdido.
Ordenação
Os eventos de webhook são despachados na ordem em que ocorrem, mas, como são enviados para várias URLs em paralelo e as condições de rede variam, a ordem de entrega não é garantida. Se sua aplicação exige ordenação estrita, use o timestamp submittedAt do payload para ordenar os eventos após o recebimento.
Tempo limite
O NueForm aguarda até 5 segundos pela resposta do seu endpoint. Se o endpoint não responder dentro dessa janela, a requisição é abortada. Seu endpoint deve responder com um código de status 2xx o mais rápido possível e adiar qualquer processamento pesado para um job em segundo plano.
Idempotência
Embora o NueForm não envie eventos duplicados por design, condições de rede (como retransmissão TCP) poderiam, em teoria, fazer com que seu endpoint recebesse o mesmo payload mais de uma vez. Use o campo responseId do payload como chave de idempotência para desduplicar com segurança.
Boas práticas
Responda rápido. Retorne
200 OKimediatamente e processe os dados do webhook de forma assíncrona. O NueForm tem um tempo limite de 5 segundos.Verifique as assinaturas. Sempre valide o cabeçalho
X-NueForm-Signatureantes de confiar no payload. Consulte Verificação.Use chaves de idempotência. Armazene os valores de
responseIdjá processados e ignore duplicatas.Reconcilie periodicamente. Complemente os webhooks em tempo real com consultas agendadas à API de Respostas para capturar eventos perdidos.
Monitore seu endpoint. Acompanhe os tempos de resposta e as taxas de erro do seu endpoint de webhook. Se o endpoint falha de forma consistente, considere implementar uma fila (por exemplo, SQS, Redis) entre o receptor de webhooks e sua lógica de processamento.
Próximos passos
- Payloads --- Veja o schema completo do payload JSON
- Verificação --- Implemente a verificação de assinatura
- Testes --- Teste a entrega de webhooks localmente