Disponibilidad del plan
Los clientes de Ask Scale pueden recibir respuestas de encuestas y respuestas de retroalimentación.
Los clientes de Observe Business pueden recibir grabaciones basadas en segmentos de grabación. Disponible en los planes . Reserva una llamada con nuestro equipo de ventas para obtener más información sobre las funciones del plan Scale.
Los clientes de Ask Scale pueden recibir respuestas de encuestas y respuestas de retroalimentación.
Los clientes de Observe Scale pueden recibir grabaciones basadas en segmentos de grabación.
Visión general
Los Webhooks de Hotjar te permiten recibir notificaciones cuando ocurre un evento, como cuando un visitante de tu sitio web envía una nueva respuesta de encuesta. Configuras un "Webhook" (una URL) en tu propio sitio web o en el sitio web de una empresa asociada, compartes ese Webhook con Hotjar y luego recibes cargas de eventos cuando ocurren eventos. Por lo tanto, los Webhooks son una forma de enviar datos a tus sistemas en tiempo real.
En términos técnicos:
- Configuras un Webhook, generalmente en tu propio servidor/sitio web, con una URL única.
- Dentro de la interfaz de Hotjar, introduces la URL del Webhook en un widget de Encuesta, widget de Retroalimentación o un Segmento de Grabación.
- Luego, Hotjar envía solicitudes POST HTTP a la URL de tu Webhook cada vez que se crea una nueva respuesta de encuesta o retroalimentación, o cuando se crea una nueva grabación que coincida con tu segmento de grabación.
¿Por qué usar Webhooks?
Los Webhooks complementan la API de Hotjar. Mientras que la API es más útil para la exportación masiva (descarga), los Webhooks son útiles para recibir inmediatamente respuestas de encuestas y retroalimentación, o grabaciones basadas en segmentos de grabación a medida que se crean. Deberías considerar usar Webhooks si:
- Quieres recibir datos de forma inmediata.
- Quieres enviar datos a tus sistemas, quizás a 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 solicitud HTTP POST a tu webhook.
- La solicitud se codificará 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:
-
event
- string. El valor de esta propiedad es el nombre del evento. En el momento de escribir esto, serásurvey_response
,feedback_response
,recording
otest_message
. -
version
- entero. Esta propiedad está reservada para uso futuro, actualmente siempre se establecerá en el número 1. -
data
- El valor de esta propiedad será un objeto JSON con los datos del evento. Los campos en el objeto son específicos para cada evento (ver más abajo).
-
Enviamos eventos tan pronto como sea posible después de que ocurran; en la práctica, deberías recibir un mensaje en solo unos pocos segundos. En circunstancias raras, los mensajes pueden retrasarse, pero cada evento incluye la fecha y hora en que ocurrieron, 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 index
que se puede utilizar para ordenar.
Requisitos del webhook
Tu webhook debe cumplir con los siguientes requisitos:
- El webhook debe ser HTTPS (TLS).
- El servidor debe responder dentro 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 solo una vez, no podemos garantizarlo. Por lo tanto, tu webhook debe depender del identificador único en el mensaje para la deduplicación.
Reintentos
Hotjar intentará reenviar el envío de un webhook en caso de un error. Hotjar reintentará hasta seis veces, con pausas entre reintentos:
Intento de reenvío | Retraso antes de reintentar |
1 | 30 segundos |
2 | 1 minuto |
3 | 2 minutos |
4 | 5 minutos |
5 | 10 minutos |
6 | 20 minutos |
Hotjar seguirá intentando enviar 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 (tras lo cual Hotjar eliminará el webhook de su widget de encuesta, widget de comentarios o segmento de grabación).
- Se alcanzan un máximo de 6 reintentos.
Firmas y prevención de repetición
Los webhooks de Hotjar utilizan dos técnicas de seguridad para asegurarse de que pueda verificar que cualquier carga útil que reciba realmente provenga de Hotjar:
- Todas las cargas útiles enviadas a sus webhooks están firmadas por HMAC; se le recomienda encarecidamente verificar la firma para asegurarse de que los datos realmente provienen de Hotjar
- Todas las cargas útiles incluyen una marca de tiempo para que pueda verificar que los datos fueron enviados por Hotjar en los últimos minutos. Esto le permite mitigar los ataques de repetición porque puede estar seguro de que Hotjar le envió estos datos en los últimos minutos.
Verificación de la firma de la carga útil
La firma se envía a su webhook como un encabezado personalizado llamado com-hotjar-signature
. Para verificar que la firma es válida, debe:
- Generar una firma a partir de la carga útil que recibió
- Comprobar si su firma generada coincide con la firma en el encabezado
Puede generar una firma utilizando HMAC-SHA3-256, la carga útil (como bytes) y una clave de firma. Para obtener la clave de firma para su sitio de Hotjar, abra la Configuración de Integración de Webhooks dentro de la aplicación de Hotjar y haga clic en "Ver clave del webhook".
Una vez que haya generado una firma, puede compararla con la firma enviada en el encabezado com-hotjar-signature
. Si los dos valores coinciden, la firma se validó correctamente; si no coinciden, debe desechar la carga útil y no actuar sobre ella.
Protección contra ataques de repetición
La firma HMAC le permite verificar que Hotjar creó la carga útil del webhook, pero un atacante podría enviar la misma carga útil nuevamente (¡una y otra vez!) y la verificación de la firma tendría éxito. Para protegerse contra estos "ataques de repetición", también enviamos una marca de tiempo dentro de la carga útil; si la fecha y hora especificadas en la marca de tiempo son demasiado antiguas (sugerimos más de 5 minutos en el pasado), debe desechar la carga útil.
Para verificar la marca de tiempo, primero debe verificar la firma HMAC, como se describe anteriormente, antes de verificar la marca de tiempo, ya que un atacante podría simplemente enviar una marca de tiempo válida dentro de una carga útil. La marca de tiempo es un sello de tiempo UNIX, lo que significa que es el número de segundos desde la época de Unix. Puede ver ejemplos de marcas de tiempo en las cargas útiles de ejemplo a continuación.
Cargas útiles
Hotjar puede agregar campos adicionales a estas cargas útiles en el futuro, por lo que su webhook no debe generar un error cuando haya un campo presente que no esperaba. Tenga en cuenta que cualquier campo también puede establecerse en nulo además del tipo indicado.
Respuesta de Comentarios
Nombre del evento: feedback_response
-
id
entero - El identificador único de la respuesta de retroalimentación. -
index
entero - El índice de esta respuesta de retroalimentación dentro del widget de retroalimentación. -
feedback_response_url
cadena - El enlace para ver la respuesta dentro de la aplicación Hotjar. -
message
cadena - El mensaje que ingresó el usuario. -
email
cadena - La dirección de correo electrónico que ingresó el usuario, si la hay. -
emotion
entero - La puntuación de emoción/reacción (1 a 5) que seleccionó el usuario. -
created_str
cadena - La fecha y hora en que se creó la respuesta de retroalimentación como una cadena ISO 8601. -
created_timestamp
entero - La fecha y hora en que se creó la respuesta de retroalimentación como una marca de tiempo UNIX. -
question
cadena - La pregunta en el widget de retroalimentación que respondió el usuario. -
site_id
entero - El identificador único del sitio de Hotjar. -
feedback_id
entero - El identificador único del widget de retroalimentación. -
feedback_name
cadena - El nombre del widget de retroalimentación. -
feedback_url
cadena - El enlace para ver el widget de retroalimentación dentro de la aplicación Hotjar. -
browser
cadena - El nombre del tipo de navegador utilizado para enviar la respuesta de retroalimentación. -
device
cadena - El tipo de dispositivo utilizado para enviar la respuesta de retroalimentación. Será "tablet", "móvil" o "escritorio". -
os
cadena - El nombre del sistema operativo utilizado para enviar la respuesta de retroalimentación. -
country_name
cadena - El país desde el cual se creó la respuesta de retroalimentación. -
country_code
cadena - El código de país desde el cual se creó la respuesta de retroalimentación. Consulta los códigos de país ISO 3166 para ver una lista de estos códigos. -
window_width
entero - El ancho de la ventana del usuario al enviar la respuesta de retroalimentación. -
window_height
entero - La altura de la ventana del usuario al enviar la respuesta de retroalimentación. -
hotjar_user_id
cadena - El ID de usuario de Hotjar para el usuario que envió la respuesta de retroalimentación (un UUID).
Respuesta de encuesta
Nombre del evento: survey_response
-
id
entero - El identificador único de la respuesta de la encuesta. -
index
entero - El índice de esta respuesta de la encuesta dentro de la encuesta. -
api_id
cadena - El ID público (incluye UUID) que hace referencia a esta respuesta de la encuesta. -
response_url
cadena - El enlace para ver la respuesta dentro de la aplicación de Hotjar. -
site_id
entero - El identificador único del sitio de Hotjar. -
survey_id
entero - El identificador único de la encuesta. -
survey_name
cadena - El nombre de la encuesta. -
survey_url
cadena - El enlace para ver la encuesta dentro de la aplicación de Hotjar. -
device
cadena - El tipo de dispositivo utilizado para enviar la respuesta de la encuesta. Será "tablet", "móvil" o "escritorio". -
browser
cadena - El nombre del tipo de navegador utilizado para enviar la respuesta de la encuesta. -
os
cadena - El nombre del sistema operativo utilizado para enviar la respuesta de la encuesta. -
country_code
cadena - El código de país desde el cual se creó la respuesta de la encuesta. Consulta los códigos de país ISO 3166 para ver una lista de estos códigos. -
country_name
cadena - El país desde el cual se creó la respuesta de la encuesta. -
hotjar_user_id
cadena - El ID de usuario de Hotjar para el usuario que envió la respuesta de la encuesta (un UUID). -
created_str
cadena - La fecha y hora en que se creó la respuesta de la encuesta como una cadena ISO 8601. -
created_timestamp
entero - La fecha y hora en que se creó la respuesta de la encuesta como una marca de tiempo UNIX. -
is_complete
booleano - Indicador que muestra si la respuesta de la encuesta está completada o no. -
recording_url
cadena - El enlace a la grabación de Hotjar que contiene esa respuesta de la encuesta, si existe. -
response_origin_url
cadena - La URL del sitio donde el usuario envió la respuesta de la encuesta. -
window_width
entero - El ancho de la ventana del usuario al enviar la respuesta de la encuesta. -
window_height
entero - La altura de la ventana del usuario al enviar la respuesta de la encuesta. -
user_attributes
objeto - Los atributos del usuario proporcionados por la API de Identificar de Hotjar. Cada clave y valor en el objeto representan lo siguiente:-
key
cadena - El nombre del atributo del usuario. -
value
cadena/entero/flotante/booleano/fecha y hora - El valor del atributo del usuario.
-
-
preguntas
array/list - Las preguntas y respuestas de la encuesta. Cada elemento tiene los siguientes campos:-
id_pregunta
entero - El ID único de la pregunta. -
texto_pregunta
cadena - El texto de la pregunta. -
tipo_pregunta
cadena - El tipo de pregunta. Será uno dereacción
,texto-largo
,texto-corto
,opción-única
,opción-múltiple
, ,correo electrónico
,valoración de 1-5
,valoración de 1-7
,nps
odesconocido
. -
respuestas
array/list - Las respuestas a la pregunta. Cada respuesta tiene los siguientes campos:-
respuesta
cadena - La respuesta que dio el usuario. -
comentario
cadena - El comentario que dejó el usuario (si lo hubiera).
-
-
Tenga en cuenta que las preguntas que el usuario no respondió no se incluyen en la carga útil.
Grabación
Nombre del evento: grabación
-
id
entero - El identificador único de la grabación. -
site_id
entero - El identificador único del sitio de Hotjar. -
country_name
cadena - El país desde el cual se registró la sesión. -
country_code
cadena - El código del país desde el cual se registró la sesión. Consulta los códigos de país ISO 3166 para ver una lista de estos códigos. -
hotjar_user_id
cadena - El ID de usuario de Hotjar para el usuario cuya sesión fue grabada (un UUID). -
device
cadena - El tipo de dispositivo utilizado por el usuario cuya sesión fue grabada. Será "tablet", "móvil" o "escritorio". -
browser
cadena - El nombre del tipo de navegador utilizado por el usuario cuya sesión fue grabada. -
browser_version
cadena - La versión del navegador utilizado por el usuario cuya sesión fue grabada. -
os
cadena - El nombre del sistema operativo utilizado por el usuario cuya sesión fue grabada. -
os_version
cadena - La versión del sistema operativo utilizado por el usuario cuya sesión fue grabada. -
action_count
entero - El número de acciones realizadas por el usuario en la sesión. -
rageclick_occurred
booleano - Se produjo un clic de ira durante la sesión grabada. -
uturn_occurred
booleano - Se produjo un giro en U durante la sesión grabada. -
created_str
cadena - La fecha y hora en que se creó la grabación como una cadena ISO 8601. -
created_timestamp
entero - La fecha y hora en que se creó la grabación como una marca de tiempo UNIX. -
referrer
cadena - La página en la que estaba el usuario antes de que comenzara su sesión de Hotjar, si está disponible. -
window_width
entero - El ancho de la ventana del usuario cuando se grabó la sesión. -
window_height
entero - La altura de la ventana del usuario cuando se grabó la sesión. -
duration
entero - La duración de la sesión grabada en milisegundos. -
relevance_score
entero - La puntuación de relevancia se basa en varios factores para determinar cuán útil es probable que sea una grabación. Estos factores incluyen la duración de la sesión, el número de páginas visitadas, el número de acciones, clics de ira, giros en U, errores de consola, escritura, eventos enviados mediante JavaScript, e interacción con formularios. -
page_urls
lista de arrays - La lista de URLs de las páginas visitadas durante la sesión. -
event_names
lista de arrays - Los eventos que ocurrieron durante la sesión grabada según lo proporcionado por la API de Eventos de Hotjar. -
landing_page_url
cadena - La página en la que estaba el usuario cuando comenzó su sesión de Hotjar. -
exit_page_url
cadena - La página en la que estaba el usuario cuando finalizó su sesión de Hotjar. -
recording_url
cadena - El enlace para ver la grabación dentro de la aplicación de Hotjar. -
user_attributes
objeto - Los atributos del usuario proporcionados por la API de Identificación de Hotjar. Cada clave y valor en el objeto representan lo siguiente:-
key
cadena - El nombre del atributo del usuario. -
value
cadena/entero/flotante/booleano/fecha y hora - El valor del atributo del usuario.
-
Mensaje de prueba
Nombre del evento: test_message
Este evento se envía al usar la aplicación Hotjar para enviar un mensaje de prueba al webhook.
muestra
cadena - Siempre se establece en la cadena "data".
Degradación del sitio
Nombre del evento: site_downgrade
Este evento se envía cuando el plan suscrito del sitio de Hotjar se degrada y ya no puede enviar mensajes a los webhooks. Hasta que el sitio se actualice nuevamente, no se enviarán más mensajes.
site_id
entero - El ID único del sitio que se degradó.
Ejemplos de cargas útiles
Respuesta de retroalimentación
{ "event": "feedback_response", "data": { "id": 32, "index": 1, "feedback_response_url": "https://fictitious.feedback-response.com/14/32", "message": "Mensaje predeterminado", "email": null, "emotion": 4, "created_str": "2023-06-07T11:26:42.287596Z", "created_timestamp": 1686137202, "question": "Esta es la pregunta inicial", "site_id": 42, "feedback_id": 42, "feedback_name": "Retroalimentación predeterminada", "feedback_url": "https://insights.hotjar.com/url/goes/here", "browser": "Chrome", "device": "Escritorio", "os": "Windows", "country_name": "Malta", "country_code": "MT", "window_width": 1024, "window_height": 768, "hotjar_user_id": "dbbc63df-1b09-4631-a837-255e162788c0" }, "version": 1,
"timestamp": 473385600 }
Respuesta de encuesta
{ "event": "survey_response", "data": { "id": 42, "index": 1, "api_id": "response_f8ccb724-8110-48d0-8715-2138be7a9c06", "response_url": "https://insights.hotjar.com/link/goes/here", "site_id": 42, "survey_id": 42, "survey_name": "Encuesta de prueba", "survey_url": "https://insights.hotjar.com/link/goes/here", "device": "Escritorio", "browser": "Chrome", "os": "Windows", "country_code": "MT", "country_name": "Malta", "hotjar_user_id": "90fc1180-90b4-463c-9d1f-3415477f0168", "created_str": "2023-06-07T11:13:05.193076Z", "created_timestamp": 1686136385, "is_complete": false, "recording_url": "https://insights.hotjar.com/r?site=14&recording=12345", "response_origin_url": "https://www.example.com", "window_width": 1280, "window_height": 1024, "user_attributes": { "test_ua_one": "valor", "test_ua_two": true }, "questions": [ { "question_id": 1, "questiom_text": "Pregunta 1", "question_type": "texto corto", "answers": [ { "answer": "La respuesta a la pregunta 1 va aquí", "comment": null } ] }, { "question_id": 2, "questiom_text": "Pregunta 2", "question_type": "texto largo", "answers": [ { "answer": "La respuesta a la pregunta 2 va aquí\n\n nueva línea", "comment": null } ] }, { "question_id": 3, "questiom_text": "Pregunta 3", "question_type": "correo electrónico", "answers": [ { "answer": "support@hotjar.com", "comment": null } ] }, { "question_id": 4, "questiom_text": "Pregunta 4", "question_type": "opción única", "answers": [ { "answer": "¿botón de radio?", "comment": "comentario" } ] }, { "question_id": 5, "questiom_text": "Pregunta 5", "question_type": "opción múltiple", "answers": [ { "answer": "esto", "comment": "comentario" }, { "answer": "aquello", "comment": "comentario" } ] }, { "question_id": 6, "questiom_text": "Pregunta 6", "question_type": "valoración de 1 a 5", "answers": [ { "answer": "3", "comment": null } ] }, { "question_id": 7, "questiom_text": "Pregunta 7", "question_type": "valoración de 1 a 7", "answers": [ { "answer": "3", "comment": null } ] }, { "question_id": 8, "questiom_text": "Pregunta 8", "question_type": "NPS", "answers": [ { "answer": "3", "comment": null } ] }, { "question_id": 9, "questiom_text": "Pregunta 9", "question_type": "reacción", "answers": [ { "answer": "3", "comment": null } ] }, { "question_id": 10, "questiom_text": "Pregunta 10", "question_type": "texto corto", "answers": [ { "answer": "", "comment": null } ] } ] }, "version": 1,
"timestamp": 473385600 }
Grabación
{
"evento": "grabación",
"datos": {
"id": 42,
"site_id":14,
"nombre_pais":"Malta",
"codigo_pais":"MT",
"id_usuario_hotjar":"90fc1180-90b4-463c-9d1f-3415477f0168",
"dispositivo":"escritorio",
"navegador":"Chrome",
"version_navegador":"51.0.2704",
"sistema_operativo":"Mac OS X",
"version_sistema_operativo":"10.11.2",
"cantidad_acciones":42,
"atributos_usuario":{
"test_ua_uno":"valor",
"test_ua_dos":true
},
"ocurrio_rageclick":true,
"ocurrio_uturn":true,
"creado_str":"2023-06-07T11:13:05.193076Z",
"timestamp_creacion":1686136385,
"referrer":"https://www.example.com",
"ancho_ventana":1024,
"alto_ventana":1280,
"duracion":50000,
"puntuacion_relevancia":4,
"urls_pagina":[
"https://www.mysite.com",
"https://www.mysite.com/login"
],
"nombres_evento":[
"Elemento de Precios Visto",
"Botón de Inicio de Sesión Clicado"
],
"url_pagina_inicio":"https://www.mysite.com",
"url_pagina_salida":"https://www.mysite.com/login",
"url_grabacion":"https://insights.hotjar.com/r?site=14&recording=123456"
},
"version": 1,
"timestamp": 473385600
}
Mensaje de Prueba
{
"evento": "mensaje_prueba",
"version": 1,
"timestamp": 473385600,
"datos": {
"ejemplo": "datos"
}
}
Degradación del Sitio
{
"evento": "degradacion_sitio",
"version": 1,
"timestamp": 473385600
"datos": {
"site_id": 12345
}
}