Referencia de Webhooks

• Visión general
• ¿Por qué usar Webhooks?
• Cómo funcionan los Webhooks
  • Requisitos de los Webhooks
  • Reintentos
  • Firmas y prevención de repeticiones
  • Cargas útiles

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:

1. Configuras un Webhook, generalmente en tu propio servidor/sitio web, con una URL única.
2. 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.
3. 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.

Volver arriba

¿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.

Volver arriba

¿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 o test_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.

Volver arriba

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.

Volver arriba

Reintentos

Hotjar intentará reenviar el envío de un webhook en caso de un error. Hotjar reintentará hasta seis veces, con pausas entre reintentos:

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.

Volver arriba

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:

1. Generar una firma a partir de la carga útil que recibió
2. 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.

Volver arriba

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 de reacció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 o desconocido. 
  • 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": "example@example.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
  }
}

Volver arriba