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.io/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.io/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.

Las entregas se firman con el secreto de webhook de la cuenta propietaria del formulario. No hace falta crearlo antes: si todavía no tienes uno, NueForm lo crea cuando abres la pestaña Desarrollador de tu Perfil, cuando llamas a GET /api/v1/webhooks/secret o en la primera entrega de uno de tus formularios. Puedes regenerarlo en cualquier momento desde esa misma pestaña o con POST /api/v1/webhooks/secret.

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

Secretos de los formularios de equipo

Las entregas de un formulario de equipo se firman con el secreto del propietario del equipo, así que verifícalas con ese secreto. NueForm no lo crea por su cuenta: mientras el propietario del equipo no tenga un secreto, las entregas de los formularios del equipo se omiten — no se envía nada ni se registra ningún intento fallido. El propietario del equipo lo crea abriendo una vez la pestaña Desarrollador de su Perfil, o llamando a GET /api/v1/webhooks/secret con su propia clave de API. La misma llamada hecha con la clave de API de otro miembro crea el secreto propio de ese miembro, que los formularios de equipo no usan.

Características de Entrega

Inicio Rápido

Para comenzar a recibir webhooks:

1. Obtén tu secreto de webhook --- Abre la pestaña Desarrollador de tu Perfil o llama a GET /api/v1/webhooks/secret. NueForm crea un secreto si aún no tienes uno. Para un formulario de equipo, usa el secreto del propietario del equipo (consulta Secretos de los formularios de equipo).
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