NueForm envía notificaciones de webhook para eventos específicos que ocurren dentro de tu cuenta. Cada solicitud de webhook incluye un campo event en el payload JSON que identifica lo que sucedió.
Eventos Actuales
form.submitted
Se dispara cuando un encuestado envía una respuesta completa a uno de tus formularios.
| Propiedad | Valor |
|---|---|
| Nombre del evento | form.submitted |
| Disparador | Un encuestado completa y envía una respuesta de formulario |
| Payload | Detalles del formulario, ID de respuesta, respuestas con marca de tiempo |
| Formularios incrementales | Solo se dispara cuando la respuesta se marca como complete |
Este es el evento de webhook principal en NueForm. Se dispara tanto para formularios estándar (envío único) como para formularios de envío incremental, pero solo cuando la respuesta alcanza un estado completado.
Cuándo se dispara:
- En un formulario estándar: inmediatamente después de que el encuestado hace clic en Enviar y la respuesta se guarda.
- En un formulario incremental: solo cuando el envío final se manda con
complete: true. Los guardados parciales no activan este evento. - En formularios de modo cuestionario (knowledge quiz, lead qualification, match quiz): el payload incluye resultados de puntuación del cuestionario junto con las respuestas.
Cuándo NO se dispara:
- Envíos parciales en formularios incrementales (donde
completeno estrue). - Ediciones a respuestas existentes (las respuestas son inmutables una vez enviadas).
- Borradores de formularios o previsualizaciones.
- Envíos de prueba desde la previsualización del constructor de formularios.
Consulta Payloads para el esquema completo del payload.
Eventos Futuros Planificados
Los siguientes eventos están planificados para futuras versiones. Aún no están disponibles pero se documentan aquí para que puedas diseñar tu integración con compatibilidad hacia adelante en mente.
Los eventos futuros listados a continuación están sujetos a cambios. Consulta el Changelog para anuncios cuando nuevos eventos estén disponibles.
form.partial
Se disparará cuando se guarde una respuesta parcial en un formulario con envío incremental habilitado. Esto te permitirá rastrear el abandono de formularios y hacer seguimiento con encuestados que empezaron pero no terminaron.
| Propiedad | Valor Planificado |
|---|---|
| Nombre del evento | form.partial |
| Disparador | Se crea o actualiza una respuesta parcial (solo formularios incrementales) |
| Payload | Misma estructura que form.submitted con un completedAt null |
form.completed
Se disparará cuando una respuesta incremental pase de parcial a completa. Esto difiere de form.submitted en que indica explícitamente que una respuesta previamente parcial ha sido finalizada.
| Propiedad | Valor Planificado |
|---|---|
| Nombre del evento | form.completed |
| Disparador | Una respuesta parcial se marca como completa |
| Payload | Misma estructura que form.submitted, incluyendo todas las respuestas acumuladas |
form.published
Se disparará cuando un formulario se publique o republique.
| Propiedad | Valor Planificado |
|---|---|
| Nombre del evento | form.published |
| Disparador | Un formulario se publica via el panel de control o la API |
| Payload | ID del formulario, título, slug, número de versión, marca de tiempo de publicación |
form.unpublished
Se disparará cuando un formulario se despublique (se retire de línea).
| Propiedad | Valor Planificado |
|---|---|
| Nombre del evento | form.unpublished |
| Disparador | Un formulario se despublica via el panel de control o la API |
| Payload | ID del formulario, título, slug, marca de tiempo de despublicación |
Garantías de Entrega de Eventos
Entender cómo NueForm entrega eventos de webhook es importante para construir integraciones confiables.
Entrega Como Máximo Una Vez
NueForm actualmente proporciona semántica de entrega como máximo una vez. Cada evento se envía una vez y no se reintenta si la entrega falla. Esto significa:
- Tu endpoint puede ocasionalmente perder eventos si está temporalmente no disponible.
- Nunca recibirás eventos duplicados para el mismo envío del sistema de entrega de NueForm.
- Debes diseñar tu integración para tolerar eventos perdidos.
Sin Reintentos Automáticos
Si tu endpoint es inaccesible, devuelve un código de estado de error, o no responde dentro de la ventana de tiempo de espera de 5 segundos, la entrega del webhook se descarta silenciosamente. NueForm no pone en cola ni reintenta entregas fallidas.
Debido a que no hay reintentos automáticos, recomendamos encarecidamente complementar los webhooks con polling periódico de la API de Respuestas para capturar cualquier evento que tu endpoint pueda haber perdido.
Ordenamiento
Los eventos de webhook se despachan en el orden en que ocurren, pero como se envían a múltiples URLs en paralelo y las condiciones de red varían, el orden de entrega no está garantizado. Si tu aplicación requiere orden estricto, usa la marca de tiempo submittedAt en el payload para ordenar los eventos después de recibirlos.
Tiempo de Espera
NueForm espera hasta 5 segundos para que tu endpoint responda. Si tu endpoint no responde dentro de esta ventana, la solicitud se aborta. Tu endpoint debe responder con un código de estado 2xx lo más rápido posible y diferir cualquier procesamiento pesado a un trabajo en segundo plano.
Idempotencia
Aunque NueForm no envía eventos duplicados por diseño, las condiciones de red (como la retransmisión TCP) podrían teóricamente causar que tu endpoint reciba el mismo payload más de una vez. Usa el campo responseId en el payload como clave de idempotencia para deduplicar de forma segura.
Mejores Prácticas
Responde rápidamente. Devuelve un
200 OKinmediatamente y procesa los datos del webhook de forma asíncrona. NueForm tiene un tiempo de espera de 5 segundos.Verifica las firmas. Siempre valida el encabezado
X-NueForm-Signatureantes de confiar en el payload. Consulta Verificación.Usa claves de idempotencia. Almacena los valores de
responseIdprocesados y omite duplicados.Reconcilia periódicamente. Complementa los webhooks en tiempo real con polling programado de la API de Respuestas para capturar cualquier evento perdido.
Monitorea tu endpoint. Rastrea tiempos de respuesta y tasas de error en tu endpoint de webhook. Si tu endpoint falla consistentemente, considera implementar una cola (por ejemplo, SQS, Redis) entre tu receptor de webhook y tu lógica de procesamiento.
Próximos Pasos
- Payloads --- Ve el esquema completo del payload JSON
- Verificación --- Implementa verificación de firma
- Pruebas --- Prueba la entrega de webhooks localmente