NueForm

Probar Webhooks

Cómo probar webhooks de NueForm durante el desarrollo local usando ngrok, webhook.site, curl y la API de NueForm.

Probar webhooks durante el desarrollo requiere que tu endpoint sea accesible desde la internet pública. Esta guía cubre varios enfoques, desde herramientas de inspección rápida hasta configuraciones completas de desarrollo local.

Opción 1: webhook.site (Inspección Rápida)

webhook.site proporciona una URL pública temporal que captura y muestra las solicitudes HTTP entrantes. Esta es la forma más rápida de ver lo que NueForm envía sin escribir código.

  1. Ve a webhook.site.
  2. Copia la URL única (por ejemplo, https://webhook.site/abc123-def456-...).
  3. Establécela como la URL de webhook de tu formulario:
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. Envía una respuesta a tu formulario.
  2. Actualiza webhook.site para ver la solicitud capturada, incluyendo encabezados, cuerpo y el X-NueForm-Signature.

webhook.site es excelente para inspección pero no te permite ejecutar lógica de verificación personalizada. Úsalo para entender el formato del payload, luego pasa a un servidor local para pruebas completas.

Opción 2: ngrok (Desarrollo Local)

ngrok crea un túnel seguro desde una URL pública a tu máquina local. Esto te permite recibir entregas de webhook reales en tu servidor de desarrollo.

Configuración

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

# O descarga desde https://ngrok.com/download
  1. Inicia tu servidor de webhook local (por ejemplo, en el puerto 3001):
bash
node server.js
# o
python app.py
  1. Inicia un túnel ngrok:
bash
ngrok http 3001
  1. Copia la URL de reenvío HTTPS de la salida de ngrok:
text
Forwarding  https://a1b2c3d4.ngrok-free.app -> http://localhost:3001
  1. Establece la URL de ngrok como tu 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. Envía una respuesta a tu formulario. El webhook llegará a tu servidor local.

Inspeccionar Tráfico

ngrok proporciona una interfaz web local en http://localhost:4040 donde puedes inspeccionar todas las solicitudes que pasan por el túnel, reproducirlas y ver encabezados y códigos de respuesta.

Las URLs gratuitas de ngrok cambian cada vez que reinicias ngrok. Recuerda actualizar tu URL de webhook en NueForm cuando obtengas una nueva URL de túnel. Considera actualizar a un plan de pago de ngrok para un subdominio estable.

Opción 3: curl (Simulando Payloads)

Puedes usar curl para enviar payloads de prueba de webhook a tu servidor local sin pasar por NueForm. Esto es útil para probar tu lógica de verificación y procesamiento de forma aislada.

Generar un Payload de Prueba Firmado

Primero, crea un payload de prueba y fírmalo con tu secreto de webhook:

bash
# Tu secreto de webhook (de la API de NueForm o el panel de control)
SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

# El payload de prueba
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"
}'

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

echo "Signature: $SIGNATURE"

Enviar la Solicitud Firmada

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

Todo en Una Línea

Combina todo en un solo 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"

Probar el Rechazo de Firma

Para verificar que tu endpoint rechaza correctamente firmas inválidas, envía una solicitud con una firma incorrecta:

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"}'

Tu endpoint debería devolver 401 Unauthorized.

Opción 4: Script de Prueba en Node.js

Crea un script independiente de Node.js para firmar y enviar payloads de prueba rápidamente:

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()}`);

Ejecútalo con:

bash
NUEFORM_WEBHOOK_SECRET=your_secret node test-webhook.mjs

Opción 5: Activar un Envío Real

La forma más completa de probar es enviar una respuesta real a tu formulario:

  1. Configura tu URL de webhook (por formulario o global) apuntando a tu endpoint de prueba.
  2. Abre tu formulario publicado en un navegador.
  3. Completa y envía el formulario.
  4. Observa la entrega del webhook en tu endpoint.

Esto prueba todo el pipeline de extremo a extremo, incluyendo validación de respuestas, puntuación de cuestionarios y el payload real que NueForm genera.

Depurar Entregas Fallidas

Si tu endpoint de webhook no está recibiendo solicitudes, trabaja a través de esta lista de verificación:

1. Verifica que la URL esté configurada

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

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

2. Verifica que la URL sea accesible

bash
# Prueba que tu endpoint acepte solicitudes POST
curl -X POST https://your-endpoint.com/webhooks/nueform \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

3. Verifica el secreto de webhook

Los webhooks solo se despachan si tu cuenta tiene un secreto de webhook establecido. Verifica:

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

Si la respuesta muestra un secreto, estás bien. Si no, uno se generará automáticamente con esta solicitud.

4. Verifica tu plan

Los webhooks requieren un plan Pro o superior. Verifica el estado de tu plan en el panel de NueForm bajo los ajustes de tu cuenta.

5. Verifica el tiempo de espera

NueForm tiene un tiempo de espera de 5 segundos. Si tu endpoint tarda más en responder, la solicitud se abortará. Asegúrate de devolver 200 OK inmediatamente y procesar los datos en segundo plano.

6. Verifica las reglas de firewall y red

Asegúrate de que tu servidor permita solicitudes POST entrantes de fuentes externas. Si estás detrás de un firewall o VPN, puede que necesites poner en lista blanca los rangos de IP de NueForm o usar ngrok.

Errores Comunes de Prueba

ErrorSolución
Usar middleware express.json() antes de la verificación de firmaUsa express.raw({ type: 'application/json' }) en la ruta del webhook
Probar con una clave API revocada o expiradaGenera una clave API nueva
Olvidar habilitar webhooks globalesEstablece "enabled": true en cada entrada de webhook global
Usar HTTP en lugar de HTTPS para la URL del webhookNueForm envía a cualquier URL que proporciones, pero usa HTTPS en producción
No verificar el secreto de webhookAsegúrate de que tu cuenta tenga un secreto de webhook antes de esperar entregas

Próximos Pasos

  • Resumen --- Cómo funcionan los webhooks en NueForm
  • Payloads --- Entiende el formato del payload
  • Verificación --- Implementa verificación de firma
Ultima actualizacion: 6 de abril de 2026