NueForm

Testando webhooks

Como testar webhooks do NueForm durante o desenvolvimento local usando ngrok, webhook.site, curl e a API do NueForm.

Testar webhooks durante o desenvolvimento exige que seu endpoint esteja acessível pela internet pública. Este guia cobre várias abordagens, de ferramentas de inspeção rápida a configurações completas de desenvolvimento local.

Opção 1: webhook.site (inspeção rápida)

O webhook.site fornece uma URL pública temporária que captura e exibe as requisições HTTP recebidas. Essa é a forma mais rápida de ver o que o NueForm envia sem escrever nenhum código.

  1. Acesse o webhook.site.
  2. Copie a URL única (por exemplo, https://webhook.site/abc123-def456-...).
  3. Defina-a como a URL de webhook do seu formulário:
bash
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://webhook.site/abc123-def456-..." }'
  1. Envie uma resposta para o seu formulário.
  2. Atualize o webhook.site para ver a requisição capturada, incluindo os cabeçalhos, o corpo e o X-NueForm-Signature.

O webhook.site é ótimo para inspeção, mas não permite executar uma lógica de verificação personalizada. Use-o para entender o formato do payload e depois passe para um servidor local para testes completos.

Opção 2: ngrok (desenvolvimento local)

O ngrok cria um túnel seguro de uma URL pública até a sua máquina local. Isso permite receber entregas reais de webhook no seu servidor de desenvolvimento.

Configuração

  1. Instale o ngrok:
bash
# macOS (Homebrew)
brew install ngrok

# Or download from https://ngrok.com/download
  1. Inicie seu servidor local de webhook (por exemplo, na porta 3001):
bash
node server.js
# or
python app.py
  1. Inicie um túnel do ngrok:
bash
ngrok http 3001
  1. Copie a URL de encaminhamento HTTPS da saída do ngrok:
text
Forwarding  https://a1b2c3d4.ngrok-free.app -> http://localhost:3001
  1. Defina a URL do ngrok como seu endpoint de webhook:
bash
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://a1b2c3d4.ngrok-free.app/webhooks/nueform" }'
  1. Envie uma resposta para o seu formulário. O webhook chegará ao seu servidor local.

Inspecionando o tráfego

O ngrok fornece uma interface web local em http://localhost:4040 onde você pode inspecionar todas as requisições que passam pelo túnel, reenviá-las e ver cabeçalhos e códigos de resposta.

As URLs gratuitas do ngrok mudam toda vez que você reinicia o ngrok. Lembre-se de atualizar sua URL de webhook no NueForm quando receber uma nova URL de túnel. Considere fazer upgrade para um plano pago do ngrok para ter um subdomínio estável.

Opção 3: curl (simulando payloads)

Você pode usar curl para enviar payloads de webhook de teste ao seu servidor local sem passar pelo NueForm. Isso é útil para testar sua lógica de verificação e processamento de forma isolada.

Gerando um payload de teste assinado

Primeiro, crie um payload de teste e assine-o com seu segredo do webhook:

bash
# Your webhook secret (from the NueForm API or dashboard)
SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

# The test payload
PAYLOAD='{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Test Form",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    { "questionId": "507f1f77bcf86cd799439033", "value": "Test answer" },
    { "questionId": "507f1f77bcf86cd799439044", "value": 5 }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}'

# Compute the HMAC-SHA256 signature
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

echo "Signature: $SIGNATURE"

Enviando a requisição assinada

bash
curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Comando único

Combine tudo em um único comando:

bash
SECRET="your_secret_here"
PAYLOAD='{"event":"form.submitted","formId":"507f1f77bcf86cd799439011","formTitle":"Test Form","responseId":"507f1f77bcf86cd799439022","answers":[{"questionId":"q1","value":"hello"}],"submittedAt":"2025-03-15T14:32:07.123Z"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Testando a rejeição de assinatura

Para verificar se o seu endpoint rejeita corretamente assinaturas inválidas, envie uma requisição com uma assinatura errada:

bash
curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: 0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{"event":"form.submitted","formId":"test","formTitle":"Test","responseId":"test","answers":[],"submittedAt":"2025-03-15T14:32:07.123Z"}'

Seu endpoint deve retornar 401 Unauthorized.

Opção 4: script de teste em Node.js

Crie um script Node.js independente para assinar e enviar payloads de teste rapidamente:

javascript
import crypto from 'crypto';

const SECRET = process.env.NUEFORM_WEBHOOK_SECRET || 'your_secret_here';
const ENDPOINT = process.env.WEBHOOK_URL || 'http://localhost:3001/webhooks/nueform';

const payload = JSON.stringify({
  event: 'form.submitted',
  formId: '507f1f77bcf86cd799439011',
  formTitle: 'Customer Feedback Survey',
  responseId: crypto.randomUUID().replace(/-/g, '').slice(0, 24),
  answers: [
    { questionId: 'q_name', value: 'Jane Doe' },
    { questionId: 'q_email', value: 'jane@example.com' },
    { questionId: 'q_rating', value: 4 },
    { questionId: 'q_feedback', value: 'Great product!' },
    { questionId: 'q_features', value: ['Feature A', 'Feature C'] },
  ],
  submittedAt: new Date().toISOString(),
});

const signature = crypto
  .createHmac('sha256', SECRET)
  .update(payload)
  .digest('hex');

const response = await fetch(ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-NueForm-Signature': signature,
  },
  body: payload,
});

console.log(`Status: ${response.status}`);
console.log(`Body: ${await response.text()}`);

Execute-o com:

bash
NUEFORM_WEBHOOK_SECRET=your_secret node test-webhook.mjs

Opção 5: disparar um envio real

A forma mais completa de testar é enviar uma resposta de verdade para o seu formulário:

  1. Configure sua URL de webhook (por formulário ou global) para apontar para o seu endpoint de teste.
  2. Abra seu formulário publicado em um navegador.
  3. Preencha e envie o formulário.
  4. Observe a entrega do webhook no seu endpoint.

Isso testa todo o pipeline de ponta a ponta, incluindo a validação das respostas, a pontuação do questionário e o payload real que o NueForm gera.

Depurando entregas com falha

Se o seu endpoint de webhook não está recebendo requisições, siga este checklist:

1. Verifique se a URL está configurada

bash
# Check per-form webhook
curl https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key"

# Check global webhooks
curl https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key"

2. Verifique se a URL está acessível

bash
# Test that your endpoint accepts POST requests
curl -X POST https://your-endpoint.com/webhooks/nueform \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

3. Verifique se há um segredo do webhook

Webhooks só são despachados se a sua conta tiver um segredo do webhook definido. Verifique:

bash
curl https://app.nueform.com/api/v1/webhooks/secret \
  -H "Authorization: Bearer nf_your_api_key"

Se a resposta mostrar um segredo, está tudo certo. Se não, um será gerado automaticamente por essa requisição.

4. Verifique seu plano

Webhooks exigem um plano Pro ou superior. Verifique o status do seu plano no painel do NueForm, nas configurações da sua conta.

5. Verifique o tempo limite

O NueForm tem um tempo limite de 5 segundos. Se o seu endpoint demorar mais para responder, a requisição será abortada. Garanta que você retorne 200 OK imediatamente e processe os dados em segundo plano.

6. Verifique as regras de firewall e rede

Garanta que seu servidor permita requisições POST recebidas de fontes externas. Se você estiver atrás de um firewall ou VPN, pode ser necessário adicionar os intervalos de IP do NueForm à lista de permissões ou usar o ngrok.

Erros comuns em testes

ErroSolução
Usar o middleware express.json() antes da verificação de assinaturaUse express.raw({ type: 'application/json' }) na rota do webhook
Testar com uma chave de API revogada ou expiradaGere uma nova chave de API
Esquecer de ativar os webhooks globaisDefina "enabled": true em cada entrada de webhook global
Usar HTTP em vez de HTTPS na URL do webhookO NueForm envia para qualquer URL que você fornecer, mas use HTTPS em produção
Não verificar se existe um segredo do webhookGaranta que sua conta tenha um segredo do webhook antes de esperar entregas

Próximos passos

Última atualização: 20 de julho de 2026