Los webhooks estándar permiten que Enquete envíe automáticamente información relacionada con las encuestas a otra aplicación cuando se produce un evento seleccionado.
Por ejemplo, cuando una persona encuestada envía o completa una encuesta, Enquete puede enviar los datos del evento directamente a su sistema de gestión de relaciones con clientes, plataforma de informes, base de datos interna, aplicación de soporte, plataforma de marketing u otro servicio externo.
Esto ayuda a su organización a automatizar flujos de trabajo y transferir datos de encuestas entre sistemas sin tener que exportar respuestas repetidamente ni trasladar la información de forma manual.
Esta guía explica cómo crear, configurar, probar, supervisar y gestionar webhooks estándar desde la interfaz de Enquete.
Importante:
Los webhooks estándar están pensados para organizaciones que tienen acceso a un desarrollador o a un equipo técnico. La aplicación receptora debe proporcionar un endpoint HTTPS de acceso público que pueda recibir solicitudes HTTP POST.
Para consultar la referencia técnica completa, incluidas las cargas útiles compatibles, los encabezados de webhook, la verificación de firmas, los esquemas de eventos y los detalles de implementación, consulte la documentación oficial de webhooks de Enquete.
Un webhook estándar es una conexión automatizada entre Enquete y una aplicación externa.
Cuando se produce un evento en una encuesta seleccionada, Enquete envía una solicitud HTTP POST a la URL del endpoint configurada en la suscripción del webhook.
Dependiendo del flujo de trabajo de su organización, un webhook puede utilizarse para:
Cada webhook estándar está vinculado a una encuesta y a un tipo de evento específicos. Esto le permite controlar qué actividades activan una entrega y a dónde se envía la información.
Antes de configurar un webhook estándar, asegúrese de que su equipo técnico haya preparado lo siguiente:
El endpoint receptor debe responder rápidamente después de aceptar una solicitud. Las operaciones de larga duración normalmente deben enviarse a una cola o a un sistema de procesamiento en segundo plano después de que el endpoint devuelva una respuesta satisfactoria.
Los desarrolladores deben consultar la documentación oficial de webhooks antes de implementar el endpoint receptor.
Desde su panel de Enquete, seleccione Integraciones en el menú superior.
Abra Webhooks estándar entre las opciones de integración disponibles.
La vista general de webhooks estándar muestra todas las suscripciones de webhook disponibles en su cuenta.
Desde esta página puede:
En la vista general de webhooks estándar, haga clic en Añadir webhook.
Se abrirá un formulario de configuración.
Introduzca el endpoint HTTPS al que Enquete debe enviar las entregas del webhook.
Por ejemplo:
https://example.com/api/enquete/webhookEl endpoint debe ser de acceso público y poder aceptar solicitudes HTTP POST.
Las direcciones localhost, las URL privadas de desarrollo y las páginas que requieren un inicio de sesión interactivo no pueden recibir entregas de webhook desde Enquete.
Introduzca una descripción que explique claramente la finalidad del webhook.
Por ejemplo:
Enviar las respuestas completadas de satisfacción del cliente a nuestro CRMUna descripción clara facilita la identificación posterior del webhook, especialmente cuando su organización gestiona varias suscripciones.
Seleccione la encuesta cuyos eventos deben activar el webhook.
Una suscripción de webhook estándar está vinculada a una sola encuesta. Si necesita enviar eventos de varias encuestas, cree una suscripción de webhook independiente para cada encuesta.
Seleccione el evento que debe activar la entrega del webhook.
Los eventos disponibles en la interfaz de webhooks estándar pueden incluir:
Los eventos disponibles pueden depender de la configuración actual de Enquete y de las funciones activadas en su cuenta.
Elija si el webhook debe estar activo inmediatamente.
Cuando un webhook está activo, Enquete envía entregas cada vez que se produce el evento seleccionado.
Cuando está inactivo, la configuración sigue disponible, pero las entregas de eventos en directo quedan pausadas.
Puede mantener un webhook inactivo mientras su equipo técnico termina de preparar o probar el endpoint receptor.
Haga clic en Guardar para crear la suscripción del webhook.
El nuevo webhook aparecerá en la vista general de webhooks estándar y podrá probarse inmediatamente.
Cada webhook estándar tiene un secreto. La aplicación receptora utiliza este secreto para verificar que una solicitud entrante procede realmente de Enquete.
El secreto del webhook debe tratarse como una contraseña o una credencial API privada.
Localice el webhook en la vista general y haga clic en el icono del ojo.
El secreto se mostrará temporalmente.
Haga clic en el icono del portapapeles para copiar el secreto.
Por motivos de seguridad, el secreto vuelve a ocultarse automáticamente después de aproximadamente diez segundos.
Entregue el secreto al desarrollador responsable del endpoint receptor y guárdelo en una ubicación segura del lado del servidor, como:
No guarde el secreto en JavaScript del frontend, repositorios públicos, capturas de pantalla, documentos compartidos ni mensajes de soporte accesibles para usuarios no autorizados.
Debe probar cada webhook antes de utilizarlo en un flujo de trabajo en producción.
Una entrega de prueba confirma que se puede acceder al endpoint y que el servidor receptor devuelve una respuesta adecuada.
Busque la suscripción del webhook en la vista general de webhooks estándar.
Haga clic en el icono del rayo en la fila del webhook.
Enquete enviará una solicitud de prueba al endpoint configurado.
Una notificación integrada mostrará el estado HTTP devuelto por el endpoint.
Una entrega satisfactoria normalmente devuelve un código de estado dentro del intervalo de 200 a 299, como:
Si la prueba falla, abra los registros de entrega para inspeccionar el estado de la respuesta, el cuerpo de la respuesta, la información del error y la duración de la solicitud.
Puede actualizar un webhook existente cuando cambien su endpoint, encuesta, tipo de evento, descripción o estado de activación.
Localice el webhook y seleccione la acción Editar.
Puede actualizar ajustes como:
Guarde el webhook después de realizar los cambios.
La configuración actualizada se utilizará para futuras entregas.
Envíe siempre otra entrega de prueba después de cambiar la URL del endpoint, la encuesta o el tipo de evento.
Los registros de entrega muestran las solicitudes que Enquete ha enviado a su endpoint y las respuestas devueltas por el servidor receptor.
Utilice estos registros para supervisar el estado de su integración e investigar las entregas fallidas.
Localice la suscripción del webhook y haga clic en el icono Ver registros situado junto al botón de eliminación.
Puede filtrar las entregas por:
Amplíe una entrada de entrega para revisar la información de diagnóstico disponible.
El registro de entrega puede incluir:
Los registros de entrega son especialmente útiles después de:
Cada solicitud de webhook contiene encabezados que ayudan a la aplicación receptora a identificar, verificar y realizar el seguimiento de la entrega.
| Encabezado | Descripción |
|---|---|
| X-Enquete-Signature | Contiene la firma utilizada para verificar que la solicitud procede de Enquete. |
| X-Enquete-Event | Identifica el tipo de evento que activó la entrega. |
| X-Enquete-Delivery | Contiene un identificador único de entrega utilizado para el seguimiento y la prevención de duplicados. |
Su equipo técnico debe utilizar el encabezado de firma para autenticar las solicitudes entrantes y el encabezado de entrega para evitar que el mismo evento se procese más de una vez.
Para conocer el formato exacto de la firma, el esquema de la carga útil y los ejemplos de implementación, consulte la documentación oficial de webhooks.
Una entrega de webhook puede intentarse más de una vez si la primera solicitud falla, supera el tiempo de espera o no devuelve una respuesta satisfactoria.
Esto significa que la aplicación receptora debe poder reconocer e ignorar de forma segura una entrega que ya se haya procesado.
Cada solicitud incluye un valor único en el encabezado X-Enquete-Delivery.
Su equipo técnico debe utilizar este valor como clave de idempotencia.
Un proceso habitual para evitar duplicados es:
Los identificadores de entrega procesados deben conservarse durante un periodo adecuado para la política de integración y reintentos de su organización.
Desactive un webhook cuando quiera detener temporalmente las entregas sin eliminar su configuración.
Puede desactivar un webhook mientras:
Cuando el webhook vuelva a activarse, podrán entregarse los futuros eventos coincidentes.
Es posible que los eventos que se produzcan mientras el webhook esté inactivo no se entreguen automáticamente más adelante.
Elimine un webhook cuando la suscripción ya no sea necesaria.
Localice el webhook y haga clic en la acción Eliminar.
Confirme que desea eliminar permanentemente la suscripción del webhook.
Después de eliminarla, Enquete dejará de enviar nuevas entregas para ese webhook.
Los registros históricos de entrega pueden seguir disponibles en los registros del backend con fines de auditoría, resolución de problemas u operaciones.
Importante: Si solo desea pausar temporalmente el webhook, desactívelo en lugar de eliminarlo.
Compruebe lo siguiente:
Las tareas de larga duración deben colocarse en una cola para su procesamiento en segundo plano en lugar de completarse antes de que el servidor devuelva la respuesta.
Pida a su equipo técnico que confirme que:
La verificación de firmas es una tarea técnica de implementación. Consulte la documentación oficial de webhooks para conocer las instrucciones actuales de verificación.
Compruebe lo siguiente:
Una respuesta 401 o 403 normalmente significa que el servidor receptor rechazó la solicitud debido a una regla de autenticación o autorización.
Compruebe si:
Una respuesta 404 normalmente significa que la URL del endpoint no coincide con una ruta disponible en el servidor receptor.
Compruebe la URL completa y confirme que la ruta existe y acepta solicitudes HTTP POST.
Una respuesta 500 indica que se ha producido un error dentro de la aplicación receptora.
Su equipo técnico debe revisar los registros del servidor de la aplicación receptora junto con la carga útil de la entrega y el identificador de entrega que aparecen en Enquete.
Las solicitudes de webhook pueden volver a intentarse después de fallos o tiempos de espera.
Su equipo técnico debe utilizar el valor X-Enquete-Delivery para identificar las entregas que ya se hayan procesado.
Antes de utilizar un webhook estándar en un flujo de trabajo en producción, confirme que ha completado lo siguiente:
Después de poner en funcionamiento el webhook, revise periódicamente las entregas fallidas y el rendimiento del endpoint para asegurarse de que la integración sigue funcionando correctamente.
Para consultar los campos de la carga útil, los esquemas de eventos, los ejemplos de verificación de firmas y otras instrucciones específicas para desarrolladores, consulte siempre la documentación oficial de webhooks de Enquete.