Visión general
Los Webhooks de Hotjar le permiten recibir notificaciones cuando se produce un evento, como cuando un visitante de su sitio web envía una nueva respuesta a una encuesta. Puede configurar un "webhook" (una URL) en su propio sitio web o en el sitio web de una empresa asociada, compartir ese webhook con Hotjar y, a continuación, recibir cargas útiles de eventos cuando se produzcan. Los webhooks son, por tanto, una forma de enviar datos a tus sistemas en tiempo real.
En términos técnicos:
- Configuras un webhook, normalmente en tu propio servidor/sitio web, con una URL única.
- En la interfaz de Hotjar introduces la URL del webhook en un widget de Encuesta o Feedback (editando el widget de Encuesta o Feedback).
- Hotjar envía peticiones HTTP POST a la URL de tu webhook cada vez que se crea una nueva encuesta o respuesta.
¿Por qué usar Webhooks?
Los webhooks complementan la API de respuestas de encuestas de Hotjar. Mientras que la API es más útil para la exportación masiva (descarga), los Webhooks son útiles para recibir inmediatamente las respuestas de encuestas y opiniones a medida que se crean. Debería considerar el uso de Webhooks si:
- Desea recibir datos inmediatamente.
- Desea enviar datos a sus sistemas, tal vez un almacén de datos, sin tener que consultar nuestra API.
- Un socio ofrece una integración con Hotjar a través de Webhooks.
Cómo funcionan los Webhooks
Cuando ocurre un evento Hotjar enviará un mensaje a cada Webhook configurado:
- El mensaje se envía como una petición HTTP POST a su webhook.
- La petición será codificada como UTF-8.
- El tipo de contenido será
application/json
. - Por lo tanto, el cuerpo de la solicitud será un objeto JSON con las siguientes propiedades:
-
evento
- cadena. El valor de esta propiedad es el nombre del evento. En el momento de escribir esto seráencuesta_respuesta
,feedback_response
omensaje_prueba
. -
versión
- entero. Esta propiedad está reservada para uso futuro, en la actualidad siempre se establecerá en el número 1. -
datos
- El valor de esta propiedad será un objeto JSON con los datos del evento. Los campos del objeto son específicos de cada evento (ver más abajo).
-
Enviamos los eventos lo antes posible después de que se produzcan; en la práctica, debería recibir un mensaje en unos pocos segundos. En raras circunstancias los mensajes pueden retrasarse, pero cada evento incluye la fecha y hora en que se produjeron, por lo que recomendamos usar eso en lugar de la fecha y hora en que tu webhook recibe un mensaje.
Hotjar no garantiza que el orden de los mensajes recibidos coincida con el orden en que ocurrieron los eventos. Algunos eventos contienen un parámetro de índice
que puede ser utilizado para ordenar.
Requisitos del webhook
Tu webhook debe cumplir los siguientes requisitos:
- El webhook debe ser HTTPS (TLS).
- El servidor debe responder antes de 10 segundos.
- El servidor debe responder con cualquier código de estado HTTP 2XX (cualquier código de estado HTTP entre 200 y 299).
- El servidor debe aceptar cualquier tipo de evento inesperado sin devolver un error.
- El servidor debe manejar mensajes duplicados accidentales. Aunque Hotjar hace todo lo posible para enviar un mensaje a tu webhook sólo una vez, no podemos garantizarlo. Por lo tanto, tu webhook debe confiar en el identificador único en el mensaje para la deduplicación.
Reintentos
Hotjar intentará reintentar el envío de un webhook en caso de error. Hotjar lo intentará hasta seis veces, haciendo una pausa entre intentos:
Intento de reintento | Retraso antes de reintentar |
1 | 30 segundos |
2 | 1 minuto |
3 | 2 minutos |
4 | 5 minutos |
5 | 10 minutos |
6 | 20 minutos |
Hotjar reintentará el envío hasta que ocurra una de las siguientes situaciones:
- El webhook responde con un código de estado 2XX (es decir, una respuesta exitosa).
- El webhook responde con un código de estado 410 (en cuyo caso Hotjar eliminará el webhook de tu encuesta o widget de feedback).
- Se alcanza un máximo de 6 reintentos.
Cargas útiles
Hotjar puede añadir campos adicionales a estos payloads en el futuro, por lo que tu webhook no debería dar un error cuando esté presente un campo que no esperabas. Ten en cuenta que cualquier campo puede ser null además del tipo indicado.
Respuesta de respuesta
Nombre del evento: feedback_response
-
id
integer- Identificador único de la respuesta. -
índice
integer - Índice de esta respuesta dentro del widget de respuesta. -
feedback_response_url
string - El enlace para ver la respuesta dentro de la aplicación Hotjar. -
mensaje
string - El mensaje introducido por el usuario. -
correo electrónico
cadena - La dirección de correo electrónico introducida por el usuario, si existe. -
emoción
integer - La puntuación de la emoción/reacción (de 1 a 5) seleccionada por el usuario. -
cadena_creada
string - La fecha y hora en que se creó la respuesta como cadena ISO 8601. -
created_timestamp
integer - Fecha y hora de creación de la respuesta en formato UNIX Timestamp. -
pregunta
string - La pregunta en el widget de retroalimentación que el usuario respondió. -
site_id
integer - El identificador único del sitio Hotjar. -
feedback_id
integer - El identificador único del widget de feedback. -
feedback_name
string - El nombre del widget de feedback. -
feedback_url
string - El enlace para ver el widget de feedback dentro de la aplicación Hotjar. -
navegador
string - El nombre del tipo de navegador utilizado para enviar la respuesta. -
dispositivo
cadena - Tipo de dispositivo utilizado para enviar la respuesta. Será "tablet", "móvil" o "escritorio". -
os
cadena - Nombre del sistema operativo utilizado para enviar la respuesta. -
nombre_país
cadena - País desde el que se creó la respuesta. -
código_país
cadena - Código del país desde el que se creó la respuesta. Consulte la lista de códigos de país ISO 3166. -
ancho_ventana
integer - Anchura de la ventana del usuario al enviar la respuesta. -
altura_ventana
integer - Altura de la ventana del usuario al enviar la respuesta. -
hotjar_user_id
string - El ID de usuario de Hotjar del usuario que envió la respuesta (un UUID).
Respuesta de la encuesta
Nombre del evento: survey_response
-
id
integer- Identificador único de la respuesta a la encuesta. -
índice
integer - Índice de esta respuesta dentro de la encuesta. -
api_id
string - El identificador público (incluye UUID) que hace referencia a esta respuesta de encuesta. -
response_url
string - El enlace para ver la respuesta dentro de la aplicación Hotjar. -
site_id
integer - El identificador único del sitio Hotjar. -
survey_id
integer - El identificador único de la encuesta. -
nombre_encuesta
string - Nombre de la encuesta. -
survey_url
string - El enlace para ver la encuesta dentro de la aplicación Hotjar. -
dispositivo
cadena - El tipo de dispositivo utilizado para enviar la respuesta de la encuesta. Será "tablet", "móvil" o "escritorio". -
navegador
cadena - Nombre del tipo de navegador utilizado para enviar la respuesta a la encuesta. -
sistema operativo
cadena - Nombre del sistema operativo utilizado para enviar la respuesta a la encuesta. -
código_país
cadena - Código del país desde el que se creó la respuesta a la encuesta. Consulte los códigos de país ISO 3166 para obtener una lista de estos códigos. -
nombre_país
cadena - País desde el que se creó la respuesta a la encuesta. -
hotjar_user_id
cadena - El ID de usuario de Hotjar del usuario que envió la respuesta a la encuesta (un UUID). -
cadena_creada
cadena - La fecha y hora en que se creó la respuesta a la encuesta como una cadena ISO 8601. -
created_timestamp
integer - Fecha y hora de creación de la respuesta a la encuesta en formato UNIX Timestamp. -
is_complete
boolean - Bandera que indica si la respuesta a la encuesta está completa o no. -
recording_url
string - Enlace a la grabación Hotjar que contiene la respuesta a la encuesta, si existe. -
response_origin_url
string - La URL del sitio donde el usuario envió la respuesta de la encuesta. -
anchura_ventana
integer - Anchura de la ventana del usuario al enviar la respuesta a la encuesta. -
altura_ventana
integer - Altura de la ventana del usuario cuando envía la respuesta a la encuesta. -
atributos_usuario
object - Los atributos del usuario proporcionados por la API Hotjar Identify. Cada clave y valor del objeto representa lo siguiente:-
clave
cadena - El nombre del atributo del usuario. -
valor
string/integer/float/boolean/datetime - El valor del atributo de usuario.
-
-
preguntas
array/list - Las preguntas y respuestas de la encuesta. Cada elemento tiene los siguientes campos:-
question_id
integer - ID único de la pregunta. -
texto_pregunta
string - El texto de la pregunta. -
tipo_pregunta
cadena - Tipo de pregunta. Será uno de los siguientesreacción
,texto largo
,texto corto
,opción única
,opción múltiple
correo electrónico
, clasificación1-5
,clasificación 1-7
,nps
odesconocido
. -
respuestas
array/list - Las respuestas a la pregunta. Cada respuesta tiene los siguientes campos:-
respuesta
cadena - La respuesta que ha dado el usuario. -
comentario
cadena - El comentario que ha dejado el usuario (si lo ha dejado).
-
-
Tenga en cuenta que las preguntas que el usuario no respondió no se incluyen en la carga útil.
Mensaje de prueba
Nombre del evento: test_message
Este evento se envía cuando se utiliza la aplicación Hotjar para enviar un mensaje de prueba al webhook.
ejemplo
string - Siempre se establece en la cadena "data".
Baja del Sitio
Nombre del evento: site_downgrade
Este evento se envía cuando el plan suscrito del Sitio Hotjar es degradado y ya no puede enviar mensajes a los webhooks. Hasta que el sitio se actualice de nuevo, no se enviarán más mensajes.
site_id
integer - El ID único del sitio que fue degradado.