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.io/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.io/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.io/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key"

# Check global webhooks
curl https://app.nueform.io/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 o segredo de assinatura

As entregas são assinadas com o segredo do webhook da conta dona do formulário. Nos seus próprios formulários não há nada a configurar: se você ainda não tiver um segredo, o NueForm o cria na primeira entrega. Em um formulário de equipe, as entregas são assinadas com o segredo do owner da equipe e são ignoradas até que o owner da equipe tenha um — veja Segredos de formulários de equipe. O owner da equipe pode conferir o dele com a própria chave de API:

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

Isso retorna o segredo da conta cuja chave de API você usa, e o cria se ele ainda não existir. Feita com a chave de API de outro membro, a mesma chamada cria o segredo desse membro, que os formulários de equipe não usam.

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
Esperar entregas de um formulário de equipe antes de o owner da equipe ter um segredoPeça ao owner da equipe que abra uma vez a aba Desenvolvedor do Perfil dele, ou que chame GET /api/v1/webhooks/secret com a própria chave de API

Próximos passos

Última atualização: 30 de outubro de 2026