Eventos de webhook

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.

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 um formulário no estilo Questionário: quando o respondente clica em Enviar. As respostas salvas automaticamente antes disso pertencem a uma resposta não concluída e não disparam este evento.
• Em formulários no modo quiz (quiz de conhecimento, qualificação de leads, quiz de correspondência): o payload traz apenas as respostas. Os resultados do quiz ficam armazenados com a resposta — busque-os na API de Respostas usando o responseId do payload (veja Resultados do quiz).

Quando NÃO dispara:

• Envios parciais em formulários incrementais (em que complete não é true).
• Respostas salvas automaticamente em um formulário no estilo Questionário antes de o respondente clicar em Enviar.
• 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.

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.

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.

form.published

Vai disparar quando um formulário for publicado ou republicado.

form.unpublished

Vai disparar quando um formulário for despublicado (tirado do ar).

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.
• Uma resposta só é concluída uma vez, então o NueForm envia o evento dela no máximo uma vez para cada URL de webhook. Mas cada URL configurada recebe a própria entrega: uma URL definida ao mesmo tempo como webhook do formulário e como webhook global recebe cada evento duas vezes. E, se as mesmas respostas forem enviadas de novo — por exemplo, um envio repetido depois de um erro de rede —, é criada uma segunda resposta, com o próprio responseId e o próprio evento.
• 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 falha e não é repetida. O NueForm registra a tentativa que falhou, mas não a coloca em fila nem a reenvia.

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

Seu endpoint pode receber o mesmo evento mais de uma vez — por exemplo, quando a mesma URL está configurada como webhook do formulário e como webhook global. Use o campo responseId do payload como chave de idempotência para desduplicar com segurança.

Boas práticas

1. Responda rápido. Retorne 200 OK imediatamente e processe os dados do webhook de forma assíncrona. O NueForm tem um tempo limite de 5 segundos.

2. Verifique as assinaturas. Sempre valide o cabeçalho X-NueForm-Signature antes de confiar no payload. Consulte Verificação.

3. Use chaves de idempotência. Armazene os valores de responseId já processados e ignore duplicatas.

4. Reconcilie periodicamente. Complemente os webhooks em tempo real com consultas agendadas à API de Respostas para capturar eventos perdidos.

5. 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