Référence des Webhooks

• Aperçu
• Pourquoi utiliser les Webhooks ?
• Comment fonctionnent les Webhooks
• Exigences des Webhooks
• Tentatives
• Signatures et prévention des rejeux
• Chargements

---

 

Aperçu

Les Webhooks Hotjar vous permettent d'être notifié lorsqu'un événement se produit, par exemple lorsqu'un visiteur de votre site Web soumet une nouvelle réponse à une enquête. Vous configurez un "webhook" (une URL) sur votre propre site Web ou sur le site Web d'une entreprise partenaire, partagez ce webhook avec Hotjar, puis recevez des charges d'événements lorsque des événements se produisent. Les Webhooks sont donc un moyen d'envoyer des données à vos systèmes en temps réel.

En termes techniques :

1. Vous configurez un webhook, généralement sur votre propre serveur/site Web, avec une URL unique.
2. Dans l'interface Hotjar, vous saisissez l'URL du webhook sur un widget d'enquête, un widget de retour d'information ou un segment d'enregistrement.
3. Hotjar envoie ensuite des requêtes POST HTTP à l'URL de votre webhook chaque fois qu'une nouvelle réponse à une enquête ou un retour d'information est créé, ou lorsqu'un nouvel enregistrement correspondant à votre segment d'enregistrement est créé.

Retour en haut

Pourquoi utiliser les Webhooks ?

Les Webhooks complètent l'API Hotjar. Alors que l'API est plus utile pour l'exportation en masse (téléchargement), les Webhooks sont utiles pour recevoir immédiatement des réponses aux enquêtes et aux retours, ou des enregistrements basés sur des segments d'enregistrement tels qu'ils sont créés. Vous devriez envisager d'utiliser les Webhooks si :

• Vous souhaitez recevoir des données immédiatement.
• Vous souhaitez envoyer des données à vos systèmes, peut-être un entrepôt de données, sans avoir à interroger notre API.
• Un partenaire propose une intégration avec Hotjar via des Webhooks.

Retour en haut

Comment fonctionnent les Webhooks

Lorsqu'un événement se produit, Hotjar envoie un message à chaque Webhook configuré :

• Le message est envoyé en tant que requête HTTP POST à votre webhook.
• La requête sera encodée en UTF-8.
• Le type de contenu sera application/json.
• Le corps de la requête sera donc un objet JSON avec les propriétés suivantes :
  • event- chaîne de caractères. La valeur de cette propriété est le nom de l'événement. Au moment de la rédaction, il s'agira de survey_response, feedback_response, recording ou test_message.
  • version- entier. Cette propriété est réservée pour une utilisation future, actuellement elle sera toujours définie sur le nombre 1.
  • data- La valeur de cette propriété sera un objet JSON avec les données de l'événement. Les champs de l'objet sont spécifiques à chaque événement (voir ci-dessous).

Nous envoyons les événements dès que possible après leur survenance ; en pratique, vous devriez recevoir un message en quelques secondes seulement. Dans des circonstances exceptionnelles, les messages peuvent être retardés, mais chaque événement inclut la date et l'heure de leur survenance, nous vous recommandons donc d'utiliser ces informations plutôt que la date et l'heure à laquelle votre webhook reçoit un message.

Hotjar ne garantit pas que l'ordre des messages reçus correspond à l'ordre des événements survenus. Certains événements contiennent un paramètre index qui peut être utilisé pour l'ordonnancement.

Retour en haut

Exigences du webhook

Votre webhook doit répondre aux exigences suivantes :

• Le webhook doit être en HTTPS (TLS).
• Le serveur doit répondre dans les 10 secondes.
• Le serveur doit répondre avec un code d'état HTTP 2XX (tout code d'état HTTP entre 200 et 299).
• Le serveur doit accepter tout type d'événement inattendu sans renvoyer d'erreur.
• Le serveur doit gérer les messages dupliqués accidentels. Bien que Hotjar fasse tout son possible pour n'envoyer un message à votre webhook qu'une seule fois, nous ne pouvons le garantir. Votre webhook doit donc se fier à l'identifiant unique dans le message pour la déduplication.

Retour en haut

Réessais

Hotjar tentera de renvoyer un webhook en cas d'erreur. Hotjar réessaiera jusqu'à six fois, en faisant une pause entre chaque réessai :

Tentative de réessai	Délai avant le réessai
1	30 secondes
2	1 minute
3	2 minutes
4	5 minutes
5	10 minutes
6	20 minutes

 

Hotjar continuera de tenter l'envoi jusqu'à ce que l'une des situations suivantes se produise :

• Le webhook répond avec un code d'état 2XX (c'est-à-dire une réponse réussie).
• Le webhook répond avec un code d'état 410 (auquel cas Hotjar supprimera le webhook de votre widget d'enquête, widget de feedback ou segment d'enregistrement).
• Maximum 6 tentatives de reprise sont atteintes.

Retour en haut

Signatures et prévention des rejeux

Les webhooks de Hotjar utilisent deux techniques de sécurité pour vous permettre de vérifier que les charges utiles que vous recevez proviennent vraiment de Hotjar :

• Toutes les charges utiles envoyées à vos webhooks sont signées par HMAC ; il est fortement recommandé de vérifier la signature pour savoir que les données proviennent vraiment de Hotjar
• Toutes les charges utiles incluent une horodatage afin que vous puissiez vérifier que les données ont été envoyées par Hotjar dans les dernières minutes. Cela vous permet de mitiger les attaques de rejeu car vous pouvez être sûr que Hotjar vous a envoyé ces données dans les dernières minutes.

Vérification de la signature de la charge utile

La signature est envoyée à votre webhook en tant qu'en-tête personnalisé nommé com-hotjar-signature. Pour vérifier que la signature est valide, vous devez :

1. Générer une signature à partir de la charge utile que vous avez reçue
2. Vérifier si votre signature générée correspond à la signature dans l'en-tête

Vous pouvez générer une signature en utilisant HMAC-SHA3-256, la charge utile (en octets) et une clé de signature. Pour obtenir la clé de signature pour votre site Hotjar, ouvrez les paramètres d'intégration des Webhooks dans l'application Hotjar et cliquez sur "Voir la clé du webhook".

Une fois que vous avez généré une signature, vous pouvez la comparer à la signature envoyée dans l'en-tête com-hotjar-signature. Si les deux valeurs correspondent, la signature a été validée avec succès ; si elles ne correspondent pas, vous devez rejeter la charge utile et ne pas agir dessus.

Protection contre les attaques de rejeu

La signature HMAC vous permet de vérifier que Hotjar a créé la charge utile du webhook, mais un attaquant pourrait envoyer la même charge utile à plusieurs reprises et la vérification de la signature réussirait. Pour se protéger contre ces "attaques de rejeu", nous envoyons également une horodatage dans la charge utile ; si la date et l'heure spécifiées dans l'horodatage sont trop anciennes (nous suggérons 5+ minutes dans le passé), vous devez rejeter la charge utile.

Pour vérifier l'horodatage, vous devez d'abord vérifier la signature HMAC, comme décrit ci-dessus, avant de vérifier l'horodatage car un attaquant pourrait simplement envoyer un horodatage valide dans une charge utile. L'horodatage est un horodatage UNIX, ce qui signifie que c'est le nombre de secondes depuis l'époque Unix. Vous pouvez voir des exemples d'horodatages dans les charges utiles d'exemple ci-dessous.

 

Retour en haut

Charges utiles

Hotjar peut ajouter des champs supplémentaires à ces charges utiles à l'avenir, donc votre webhook ne doit pas générer d'erreur lorsqu'un champ est présent auquel vous ne vous attendiez pas. Notez que tout champ peut être défini sur null en plus du type indiqué.

Réponse de feedback

Nom de l'événement : feedback_response 

• id entier - L'identifiant unique de la réponse au feedback.
• index entier - L'index de cette réponse au feedback dans le widget de feedback.
• feedback_response_url chaîne de caractères - Le lien pour visualiser la réponse dans l'application Hotjar.
• message chaîne de caractères - Le message saisi par l'utilisateur.
• email chaîne de caractères - L'adresse e-mail saisie par l'utilisateur, le cas échéant.
• emotion entier - Le score d'émotion/réaction (de 1 à 5) sélectionné par l'utilisateur.
• created_str chaîne de caractères - La date et l'heure de création de la réponse au feedback au format ISO 8601.
• created_timestamp entier - La date et l'heure de création de la réponse au feedback en tant que timestamp UNIX.
• question chaîne de caractères - La question sur le widget de feedback à laquelle l'utilisateur a répondu.
• site_id entier - L'identifiant unique du site Hotjar.
• feedback_id entier - L'identifiant unique du widget de feedback.
• feedback_name chaîne de caractères - Le nom du widget de feedback.
• feedback_url chaîne de caractères - Le lien pour visualiser le widget de feedback dans l'application Hotjar.
• browser chaîne de caractères - Le nom du type de navigateur utilisé pour soumettre la réponse au feedback.
• device chaîne de caractères - Le type d'appareil utilisé pour soumettre la réponse au feedback. Il sera "tablette", "mobile" ou "ordinateur de bureau".
• os chaîne de caractères - Le nom du système d'exploitation utilisé pour soumettre la réponse au feedback.
• country_name chaîne de caractères - Le pays à partir duquel la réponse au feedback a été créée.
• country_code chaîne de caractères - Le code pays à partir duquel la réponse au feedback a été créée. Consultez les codes pays ISO 3166 pour une liste de ces codes.
• window_width entier - La largeur de la fenêtre de l'utilisateur lors de la soumission de la réponse au feedback.
• window_height entier - La hauteur de la fenêtre de l'utilisateur lors de la soumission de la réponse au feedback.
• hotjar_user_id chaîne de caractères - L'identifiant utilisateur Hotjar de l'utilisateur ayant soumis la réponse au feedback (un UUID).

Réponse au sondage

Nom de l'événement : survey_response

• id entier - L'identifiant unique de la réponse au sondage.
• index entier - L'index de cette réponse au sondage dans le sondage.
• api_id chaîne de caractères - L'identifiant public (inclut l'UUID) faisant référence à cette réponse au sondage.
• response_url chaîne de caractères - Le lien pour visualiser la réponse dans l'application Hotjar.
• site_id entier - L'identifiant unique du site Hotjar.
• survey_id entier - L'identifiant unique du sondage.
• survey_name chaîne de caractères - Le nom du sondage.
• survey_url chaîne de caractères - Le lien pour visualiser le sondage dans l'application Hotjar.
• device chaîne de caractères - Le type d'appareil utilisé pour soumettre la réponse au sondage. Il peut s'agir d'une "tablette", d'un "mobile" ou d'un "ordinateur de bureau".
• browser chaîne de caractères - Le nom du navigateur utilisé pour soumettre la réponse au sondage.
• os chaîne de caractères - Le nom du système d'exploitation utilisé pour soumettre la réponse au sondage.
• country_code chaîne de caractères - Le code pays à partir duquel la réponse au sondage a été créée. Consultez les codes pays ISO 3166 pour une liste de ces codes.
• country_name chaîne de caractères - Le pays à partir duquel la réponse au sondage a été créée.
• hotjar_user_id chaîne de caractères - L'identifiant utilisateur Hotjar de l'utilisateur ayant soumis la réponse au sondage (un UUID).
• created_str chaîne de caractères - La date et l'heure à laquelle la réponse au sondage a été créée sous forme de chaîne ISO 8601.
• created_timestamp entier - La date et l'heure à laquelle la réponse au sondage a été créée sous forme de timestamp UNIX.
• is_complete booléen - Indicateur indiquant si la réponse au sondage est complète ou non.
• recording_url chaîne de caractères - Le lien vers l'enregistrement Hotjar contenant cette réponse au sondage, s'il existe.
• response_origin_url chaîne de caractères - L'URL du site où l'utilisateur a soumis la réponse au sondage.
• window_width entier - La largeur de la fenêtre de l'utilisateur lors de la soumission de la réponse au sondage.
• window_height entier - La hauteur de la fenêtre de l'utilisateur lors de la soumission de la réponse au sondage.
• user_attributes objet - Les attributs de l'utilisateur tels que fournis par l'API Hotjar Identify. Chaque clé et valeur dans l'objet représentent ce qui suit :
  • key chaîne de caractères - Le nom de l'attribut de l'utilisateur.
  • value chaîne de caractères/entier/décimal/booléen/date-heure - La valeur de l'attribut de l'utilisateur.
• questions tableau/liste - Les questions et réponses du sondage. Chaque élément a les champs suivants :
  • question_id entier - L'identifiant unique de la question.
  • question_text chaîne de caractères - Le texte de la question.
  • question_type chaîne de caractères - Le type de question. Il s'agira de l'un des suivants : réaction, texte-long, texte-court, option-simple, option-multiple, , email, notation-1-5, notation-1-7, nps ou inconnu.
  • answers tableau/liste - Les réponses à la question. Chaque réponse a les champs suivants :
    • answer chaîne de caractères - La réponse donnée par l'utilisateur.
    • comment chaîne de caractères - Le commentaire laissé par l'utilisateur (le cas échéant).

Veuillez noter que les questions auxquelles l'utilisateur n'a pas répondu ne sont pas incluses dans la charge utile.

Enregistrement

Nom de l'événement : enregistrement

• id entier - L'identifiant unique de l'enregistrement.
• site_id entier - L'identifiant unique du site Hotjar.
• country_name chaîne de caractères - Le pays où la session enregistrée s'est déroulée.
• country_code chaîne de caractères - Le code pays d'où la session enregistrée s'est déroulée. Consultez les codes pays ISO 3166 pour une liste de ces codes.
• hotjar_user_id chaîne de caractères - L'identifiant utilisateur Hotjar de l'utilisateur dont la session a été enregistrée (un UUID).
• device chaîne de caractères - Le type d'appareil utilisé par l'utilisateur dont la session a été enregistrée. Il peut s'agir d'une "tablette", d'un "mobile" ou d'un "ordinateur de bureau".
• browser chaîne de caractères - Le nom du navigateur utilisé par l'utilisateur dont la session a été enregistrée.
• browser_version chaîne de caractères - La version du navigateur utilisée par l'utilisateur dont la session a été enregistrée.
• os chaîne de caractères - Le nom du système d'exploitation utilisé par l'utilisateur dont la session a été enregistrée.
• os_version chaîne de caractères - La version du système d'exploitation utilisée par l'utilisateur dont la session a été enregistrée.
• action_count entier - Le nombre d'actions effectuées par l'utilisateur lors de la session.
• rageclick_occurred booléen - Un clic de rage s'est produit pendant la session enregistrée.
• uturn_occurred booléen - Un demi-tour s'est produit pendant la session enregistrée.
• created_str chaîne de caractères - La date et l'heure de création de l'enregistrement sous forme de chaîne ISO 8601.
• created_timestamp entier - La date et l'heure de création de l'enregistrement sous forme de timestamp UNIX.
• referrer chaîne de caractères - La page sur laquelle l'utilisateur se trouvait avant le début de sa session Hotjar, si disponible.
• window_width entier - La largeur de la fenêtre de l'utilisateur lors de l'enregistrement de la session.
• window_height entier - La hauteur de la fenêtre de l'utilisateur lors de l'enregistrement de la session.
• duration entier - La durée de la session enregistrée en millisecondes.
• relevance_score entier - Le score de pertinence est basé sur plusieurs facteurs pour déterminer à quel point un enregistrement est susceptible d'être utile. Ces facteurs incluent la durée de la session, le nombre de pages visitées, le nombre d'actions, les clics de rage, les demi-tours, les erreurs de console, la saisie, les événements envoyés via JavaScript, et l'interaction avec les formulaires.
• page_urls liste/tableau - La liste des URL des pages visitées pendant la session.
• event_names liste/tableau - Les événements survenus lors de la session enregistrée tels que fournis par l'API des événements Hotjar.
• landing_page_url chaîne de caractères - La page sur laquelle l'utilisateur se trouvait au début de sa session Hotjar.
• exit_page_url chaîne de caractères - La page sur laquelle l'utilisateur se trouvait à la fin de sa session Hotjar.
• recording_url chaîne de caractères - Le lien pour visualiser l'enregistrement dans l'application Hotjar.
• user_attributes objet - Les attributs de l'utilisateur tels que fournis par l'API Hotjar Identify. Chaque clé et valeur dans l'objet représentent ce qui suit :
  • key chaîne de caractères - Le nom de l'attribut de l'utilisateur.
  • value chaîne de caractères/entier/décimal/booléen/date et heure - La valeur de l'attribut de l'utilisateur.

Message de test

Nom de l'événement : test_message

Cet événement est envoyé lors de l'utilisation de l'application Hotjar pour envoyer un message de test au webhook.

exemple chaîne de caractères - Toujours défini sur la chaîne "data".

Régression du site

Nom de l'événement : site_downgrade

Cet événement est envoyé lorsque le plan abonné du site Hotjar est rétrogradé et ne peut plus envoyer de messages aux webhooks. Jusqu'à ce que le site se mette à niveau à nouveau, aucun autre message ne sera envoyé.

site_id entier - L'identifiant unique du site qui a été rétrogradé.

Exemples de charges utiles

Réponse de feedback

{
  "event": "feedback_response",
  "data": {
    "id": 32,
    "index": 1,
    "feedback_response_url": "https://fictitious.feedback-response.com/14/32",
    "message": "Message par défaut",
    "email": null,
    "emotion": 4,
    "created_str": "2023-06-07T11:26:42.287596Z",
    "created_timestamp": 1686137202,
    "question": "Ceci est la question initiale",
    "site_id": 42,
    "feedback_id": 42,
    "feedback_name": "Feedback par défaut",
    "feedback_url": "https://insights.hotjar.com/url/goes/here",
    "browser": "Chrome",
    "device": "Desktop",
    "os": "Windows",
    "country_name": "Malte",
    "country_code": "MT",
    "window_width": 1024,
    "window_height": 768,
    "hotjar_user_id": "dbbc63df-1b09-4631-a837-255e162788c0"
  },
  "version": 1,
  "timestamp": 473385600
}

Réponse de sondage

{
  "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": "Test survey",
    "survey_url": "https://insights.hotjar.com/link/goes/here",
    "device": "Desktop",
    "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": "value",
      "test_ua_two": true
    },
    "questions": [
      {
        "question_id": 1,
        "questiom_text": "Question 1",
        "question_type": "short-text",
        "answers": [
          {
            "answer": "Answer to question 1 goes here",
            "comment": null
          }
        ]
      },
      {
        "question_id": 2,
        "questiom_text": "Question 2",
        "question_type": "long-text",
        "answers": [
          {
            "answer": "Answer to question 2 goes here\n\n new line",
            "comment": null
          }
        ]
      },
      {
        "question_id": 3,
        "questiom_text": "Question 3",
        "question_type": "email",
        "answers": [
          {
            "answer": "support@hotjar.com",
            "comment": null
          }
        ]
      },
      {
        "question_id": 4,
        "questiom_text": "Question 4",
        "question_type": "single-option",
        "answers": [
          {
            "answer": "radio button?",
            "comment": "comment"
          }
        ]
      },
      {
        "question_id": 5,
        "questiom_text": "Question 5",
        "question_type": "multiple-option",
        "answers": [
          {
            "answer": "this",
            "comment": "comment"
          },
          {
            "answer": "that",
            "comment": "comment"
          }
        ]
      },
      {
        "question_id": 6,
        "questiom_text": "Question 6",
        "question_type": "1-5-rating",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 7,
        "questiom_text": "Question 7",
        "question_type": "1-7-rating",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 8,
        "questiom_text": "Question 8",
        "question_type": "nps",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 9,
        "questiom_text": "Question 9",
        "question_type": "reaction",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 10,
        "questiom_text": "Question 10",
        "question_type": "short-text",
        "answers": [
          {
            "answer": "",
            "comment": null
          }
        ]
      }
    ]
  },
  "version": 1,
  "timestamp": 473385600
}

Enregistrement

{
  "event": "enregistrement",
  "data": {
    "id": 42,
    "site_id":14,
    "country_name":"Malte",
    "country_code":"MT",
    "hotjar_user_id":"90fc1180-90b4-463c-9d1f-3415477f0168",
    "device":"ordinateur de bureau",
    "browser":"Chrome",
    "browser_version":"51.0.2704",
    "os":"Mac OS X",
    "os_version":"10.11.2",
    "action_count":42,
    "user_attributes":{
      "test_ua_one":"valeur",
      "test_ua_two":true
    },
    "rageclick_occurred":true,
    "uturn_occurred":true,
    "created_str":"2023-06-07T11:13:05.193076Z",
    "created_timestamp":1686136385,
    "referrer":"https://www.example.com",
    "window_width":1024,
    "window_height":1280,
    "duration":50000,
    "relevance_score":4,
    "page_urls":[
      "https://www.mysite.com",
      "https://www.mysite.com/login"
    ],
    "event_names":[
      "Vue de l'élément de tarification",
      "Clic sur le bouton de connexion"
    ],
    "landing_page_url":"https://www.mysite.com",
    "exit_page_url":"https://www.mysite.com/login",
    "recording_url":"https://insights.hotjar.com/r?site=14&recording=123456"
  },
  "version": 1,
  "timestamp": 473385600
}

Message de test

{
  "event": "message_de_test",
  "version": 1,
  "timestamp": 473385600,
  "data": {
    "sample": "données"
  }
}

Régression du site

{
  "event": "site_downgrade",
  "version": 1,
  "timestamp": 473385600
  "data": {
    "site_id": 12345
  }
}

Retour en haut