Resumen de Webhooks

Los webhooks permiten que tu aplicación reciba notificaciones HTTP en tiempo real cada vez que algo sucede en NueForm. En lugar de hacer polling a la API para nuevas respuestas, NueForm envía datos a tu servidor en el momento en que se envía un formulario.

Cómo Funcionan los Webhooks

Cuando un encuestado envía un formulario, NueForm inmediatamente envía una solicitud HTTP POST a cada URL de webhook que hayas configurado. El cuerpo de la solicitud contiene un payload JSON firmado con el tipo de evento, detalles del formulario y las respuestas enviadas.

El flujo se ve así:

1. Un encuestado completa y envía tu formulario.
2. NueForm valida las respuestas y almacena la respuesta.
3. NueForm construye un payload JSON conteniendo los datos del evento.
4. NueForm firma el payload con tu secreto de webhook usando HMAC-SHA256.
5. NueForm envía el payload como una solicitud POST a cada URL configurada.
6. Tu servidor recibe la solicitud, verifica la firma y procesa los datos.

La entrega de webhooks es disparar y olvidar y no bloqueante. Los fallos de webhook nunca afectan el flujo de envío --- los encuestados siempre ven un envío exitoso independientemente de si tu endpoint de webhook es accesible.

Webhooks por Formulario vs. Globales

NueForm soporta dos tipos de configuración de webhook:

Webhooks por Formulario

Cada formulario puede tener su propia URL de webhook dedicada. Esto es útil cuando quieres que diferentes formularios notifiquen a diferentes sistemas --- por ejemplo, enviar envíos de formularios de soporte a tu helpdesk y envíos de formularios de retroalimentación a tu pipeline de analítica.

Puedes establecer una URL de webhook por formulario a través de:

• El Panel de NueForm --- Abre los ajustes de tu formulario e ingresa la URL del webhook.
• La API --- Usa la API de Webhooks para establecer o actualizar la URL programáticamente.

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 Globales

Los webhooks globales se disparan para cada formulario en tu cuenta. Son útiles para registro centralizado, analítica o integraciones CRM que necesitan procesar todos los envíos independientemente de qué formulario provengan.

Puedes configurar hasta 5 webhooks globales, y cada uno puede ser habilitado o deshabilitado individualmente.

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

Orden de Entrega

Cuando se envía un formulario, NueForm despacha webhooks a todas las URLs aplicables en paralelo:

1. La URL de webhook por formulario del formulario (si está establecida).
2. Todas las URLs de webhooks globales habilitadas.

Cada destino recibe el mismo payload con la misma firma.

Cuándo se Disparan los Webhooks

Actualmente, los webhooks se disparan en un solo evento:

Para formularios con envío incremental habilitado, el webhook se dispara solo cuando la respuesta se marca como completa --- los guardados parciales no activan webhooks.

Consulta Eventos para la referencia completa de eventos y eventos futuros planificados.

Seguridad de Webhooks

Cada solicitud de webhook incluye un encabezado X-NueForm-Signature que contiene un digest hexadecimal HMAC-SHA256 del cuerpo de la solicitud. Siempre debes verificar esta firma antes de procesar datos de webhook para asegurar que la solicitud proviene genuinamente de NueForm.

Tu secreto de webhook se genera automáticamente la primera vez que accedes a él y puede ser regenerado en cualquier momento a través de la API o el panel de control.

Consulta Verificación para detalles de implementación y ejemplos de código.

Características de Entrega

Inicio Rápido

Para comenzar a recibir webhooks:

1. Obtén tu secreto de webhook --- Llama a GET /api/v1/webhooks/secret o encuéntralo en tu panel de control bajo configuración de Desarrollador. NueForm genera automáticamente un secreto si aún no tienes uno.
2. Configura una URL de webhook --- Configura una URL por formulario o agrega un webhook global.
3. Implementa tu endpoint --- Construye un endpoint HTTP que acepte solicitudes POST, verifique la firma y procese el payload.
4. Pruébalo --- Usa una herramienta como webhook.site o ngrok para verificar la entrega antes de ir a producción. Consulta Probar Webhooks para instrucciones detalladas.

Próximos Pasos

• Eventos --- Aprende sobre los tipos de eventos de webhook
• Payloads --- Ve el esquema completo del payload y ejemplos
• Verificación --- Implementa verificación de firma HMAC-SHA256
• Pruebas --- Prueba webhooks durante el desarrollo local