Artículos en esta sección

Referencia de Webhooks

Disponible en los planes Scale plan label.

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:

  1. Configuras un webhook, normalmente en tu propio servidor/sitio web, con una URL única.
  2. En la interfaz de Hotjar introduces la URL del webhook en un widget de Encuesta o Feedback (editando el widget de Encuesta o Feedback).
  3. Hotjar envía peticiones HTTP POST a la URL de tu webhook cada vez que se crea una nueva encuesta o respuesta.

Volver arriba

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

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 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 o mensaje_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.

Volver arriba

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.

Volver arriba

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.

Volver arriba

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 siguientes reacción, texto largo, texto corto, opción única, opción múltiple correo electrónico, clasificación 1-5, clasificación 1-7, nps o desconocido.
    • 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.

Volver arriba

Artículos relacionados