Visão geral de webhooks

Webhooks permitem que sua aplicação receba notificações HTTP em tempo real sempre que algo acontece no NueForm. Em vez de consultar a API em busca de novas respostas, o NueForm envia os dados para o seu servidor no momento em que um formulário é enviado.

Webhooks estão disponíveis no plano Pro (US$ 29/mês) e superiores. Usuários do plano Entrepreneur (gratuito) precisarão fazer upgrade para usar webhooks.

Como os webhooks funcionam

Quando um respondente envia um formulário, o NueForm imediatamente faz uma requisição HTTP POST para cada URL de webhook que você configurou. O corpo da requisição contém um payload JSON assinado com o tipo do evento, os detalhes do formulário e as respostas enviadas.

O fluxo funciona assim:

Um respondente preenche e envia seu formulário.
O NueForm valida as respostas e armazena a resposta.
O NueForm monta um payload JSON contendo os dados do evento.
O NueForm assina o payload com seu segredo do webhook usando HMAC-SHA256.
O NueForm envia o payload como uma requisição POST para cada URL configurada.
Seu servidor recebe a requisição, verifica a assinatura e processa os dados.

A entrega de webhooks é fire-and-forget e não bloqueante. Falhas do webhook nunca afetam o fluxo de envio --- os respondentes sempre veem um envio bem-sucedido, independentemente de o seu endpoint de webhook estar acessível ou não.

Webhooks por formulário vs. globais

O NueForm oferece suporte a dois tipos de configuração de webhook:

Webhooks por formulário

Cada formulário pode ter sua própria URL de webhook dedicada. Isso é útil quando você quer que formulários diferentes notifiquem sistemas diferentes --- por exemplo, enviando os envios do formulário de suporte para o seu helpdesk e os envios do formulário de feedback para o seu pipeline de analytics.

Você pode definir uma URL de webhook por formulário através de:

O painel do NueForm --- Abra as configurações do seu formulário e insira a URL do webhook.
A API --- Use a API de Webhooks para definir ou atualizar a URL de forma programática.

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhooks/nueform" }'

Webhooks globais

Webhooks globais disparam para todos os formulários da sua conta. Eles são úteis para logging centralizado, analytics ou integrações de CRM que precisam processar todos os envios, independentemente do formulário de origem.

Você pode configurar até 5 webhooks globais, e cada um pode ser ativado ou desativado individualmente.

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://analytics.example.com/nueform", "enabled": true },
      { "url": "https://crm.example.com/inbound", "enabled": true },
      { "url": "https://staging.example.com/test", "enabled": false }
    ]
  }'

Ordem de entrega

Quando um formulário é enviado, o NueForm dispara webhooks para todas as URLs aplicáveis em paralelo:

A URL de webhook por formulário do próprio formulário (se definida).
Todas as URLs de webhook globais ativadas.

Todos os destinos recebem o mesmo payload com a mesma assinatura.

Quando os webhooks disparam

Atualmente, os webhooks disparam em um único evento:

Evento	Gatilho
`form.submitted`	Um respondente envia uma resposta completa

Para formulários com envio incremental ativado, o webhook dispara apenas quando a resposta é marcada como completa --- salvamentos parciais não disparam webhooks.

Consulte Eventos para a referência completa de eventos e os eventos futuros planejados.

Segurança de webhooks

Toda requisição de webhook inclui um cabeçalho X-NueForm-Signature contendo um digest hexadecimal HMAC-SHA256 do corpo da requisição. Você deve sempre verificar essa assinatura antes de processar os dados do webhook para garantir que a requisição realmente veio do NueForm.

Seu segredo do webhook é gerado automaticamente na primeira vez que você o acessa e pode ser regenerado a qualquer momento pela API ou pelo painel.

Consulte Verificação para detalhes de implementação e exemplos de código.

Características de entrega

Propriedade	Valor
Método HTTP	`POST`
Tipo de conteúdo	`application/json`
Tempo limite	5 segundos
Política de novas tentativas	Sem novas tentativas automáticas (fire-and-forget)
Cabeçalho de assinatura	`X-NueForm-Signature`
Algoritmo de assinatura	HMAC-SHA256 (digest hexadecimal)

O NueForm atualmente usa um modelo de entrega fire-and-forget com tempo limite de 5 segundos e sem novas tentativas automáticas. Se o seu endpoint estiver inacessível ou retornar um erro, a entrega do webhook é descartada silenciosamente. Projete sua integração para lidar com entregas perdidas ocasionais --- por exemplo, reconciliando periodicamente pela API de Respostas.

Início rápido

Para começar a receber webhooks:

Obtenha seu segredo do webhook --- Chame GET /api/v1/webhooks/secret ou encontre-o no seu painel em Developer settings. O NueForm gera um segredo automaticamente se você ainda não tiver um.
Configure uma URL de webhook --- Defina uma URL por formulário ou adicione um webhook global.
Implemente seu endpoint --- Crie um endpoint HTTP que aceite requisições POST, verifique a assinatura e processe o payload.
Teste --- Use uma ferramenta como o webhook.site ou o ngrok para verificar a entrega antes de ir para produção. Consulte Testando webhooks para instruções detalhadas.

Próximos passos

Eventos --- Conheça os tipos de evento de webhook
Payloads --- Veja o schema completo do payload e exemplos
Verificação --- Implemente a verificação de assinatura HMAC-SHA256
Testes --- Teste webhooks durante o desenvolvimento local