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

# Verificar webhooks globales
curl https://app.nueform.io/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 firma

Las entregas se firman con el secreto de webhook de la cuenta propietaria del formulario. En tus propios formularios no hay nada que configurar: si aún no tienes un secreto, NueForm lo crea en la primera entrega. En un formulario de equipo, las entregas se firman con el secreto del propietario del equipo y se omiten hasta que el propietario del equipo tenga uno; consulta Secretos de los formularios de equipo. El propietario del equipo puede comprobar el suyo con su propia clave de API:

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

Esto devuelve el secreto de la cuenta cuya clave de API usas, y lo crea si todavía no existe. Hecha con la clave de API de otro miembro, la misma llamada crea el secreto propio de ese miembro, que los formularios de equipo no usan.

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
Esperar entregas de un formulario de equipo antes de que el propietario del equipo tenga un secretoPide al propietario del equipo que abra una vez la pestaña Desarrollador de su Perfil, o que llame a GET /api/v1/webhooks/secret con su propia clave de API

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: 8 de octubre de 2026