Référence des Webhooks du Voice of Customer

• Aperçu
• Pourquoi utiliser les Webhooks ?
• Comment fonctionnent les Webhooks ?
• Exigences relatives aux Webhooks
• Réessais
• Signatures et prévention des rediffusions
• Charges utiles

---

 

Aperçu

Les Webhooks vous permettent d'être informé lorsqu'un événement se produit, par exemple lorsqu'un visiteur de votre site web soumet une nouvelle réponse à une enquête. En gros, vous configurez un "Webhook" (une URL) sur votre propre site web ou sur le site web d'une entreprise partenaire, vous partagez ce Webhook avec Contentsquare et vous recevez alors des charges utiles 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 créez un Webhook, généralement sur votre propre serveur/site web, avec une URL unique.
2. Vous saisissez l'URL du Webhook dans la section "Transfert de réponses" lorsque vous  configurez une enquête.
3. Nous envoyons ensuite des requêtes HTTP POST à l'URL de votre Webhook chaque fois qu'une nouvelle réponse à l'enquête est soumise.

Retour au haut de la page

Pourquoi utiliser les Webhooks ?

Les Webhooks complètent l'API du Voice of Customer de Hotjar. Tandis que cette dernière est plus utile pour l'exportation en masse (téléchargement), les Webhooks, eux, sont utiles pour recevoir immédiatement les réponses à une enquête. 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, éventuellement à un entrepôt de données, sans avoir à interroger notre API.
• un partenaire propose une intégration avec Hotjar via des Webhooks.

Retour au haut de la page

Comment fonctionnent les Webhooks ?

Lorsqu'un événement se produit, nous envoyons un message à tous les Webhooks configurés :

• Le message est envoyé sous la forme d'une 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 du présent document, il s'agira de survey_response ou test_message .
  • version - nombre entier. Cette propriété est réservée pour une utilisation future ; pour l'instant, elle est toujours fixée à 1.
  • data - La valeur de cette propriété est un objet JSON contenant 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 qu'ils surviennent ; en pratique, vous devriez recevoir un message dans les quelques secondes qui suivent. Dans de rares circonstances, les messages peuvent être retardés, mais chaque événement comprend la date et l'heure auxquelles il s'est produit. Nous vous recommandons donc d'utiliser cette date plutôt que la date et l'heure auxquelles votre Webhook a reçu le message.

Contentsquare ne garantit pas que l'ordre des messages reçus corresponde à l'ordre dans lequel les événements se sont produits. Certains événements contiennent un paramètre index qui peut être utilisé pour l'ordre.

Retour au haut de la page

Exigences relatives aux Webhooks

Votre Webhook doit répondre aux exigences suivantes :

• Le Webhook doit être HTTPS (TLS).
• Le serveur doit répondre dans les 10 secondes.
• Le serveur doit répondre avec n'importe quel code d'état HTTP 2XX (tout code d'état HTTP compris entre 200 et 299).
• Le serveur doit accepter tout type d'événement inattendu sans renvoyer d'erreur.
• Le serveur doit gérer les doublons accidentels. Bien que nous fassions tout notre possible pour n'envoyer qu'une seule fois un message à votre Webhook, nous ne pouvons pas le garantir. Votre Webhook doit donc s'appuyer sur l'identifiant unique du message pour la déduplication.

Retour au haut de la page

Réessais

En cas d'erreur, nous tenterons de relancer l'envoi d'un Webhook jusqu'à six fois, en marquant une pause entre les tentatives :

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

Nous réessayerons 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 (nous supprimons alors le Webhook de votre enquête).
• Le nombre maximum de 6 tentatives est atteint.

Retour au haut de la page

Signatures et prévention des replay

Nos Webhooks utilisent deux techniques de sécurité pour vous permettre de vérifier que les données utiles que vous recevez proviennent bien de nous :

• Toutes les données utiles envoyées à vos Webhooks sont signées par HMAC ; nous vous encourageons vivement à vérifier la signature afin de vous assurer que les données proviennent bien de nous.
• Toutes les données utiles comprennent un horodatage qui vous permet de vérifier que les données ont été envoyées depuis /us au cours des dernières minutes. Cela vous permet d'atténuer les attaques à répétition, car vous pouvez être sûr que nous vous avons envoyé ces données au cours des dernières minutes.

Vérification de la signature de la charge utile

La signature est envoyée à votre Webhook sous la forme d'un 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 reçue
2. vérifier si la signature générée correspond à la signature de 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 de votre site, ouvrez la page Intégrations et cliquez sur "Webhooks". Cliquez ensuite sur "Voir la clé 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 en conséquence.

Protection contre les attaques à répétition

La signature HMAC vous permet de vérifier que nous avons créé la charge utile du Webhook, mais un pirate pourrait envoyer la même charge utile à plusieurs reprises (et encore à plusieurs reprises !) et la vérification de la signature réussirait. Si la date et l'heure spécifiées dans l'horodatage sont trop anciennes (nous suggérons qu'elles remontent à plus de 5 minutes), 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 pirate pourrait simplement envoyer un horodatage valide dans une charge utile. L'horodatage est un horodatage UNIX, ce qui signifie qu'il s'agit du nombre de secondes écoulées depuis l'époque Unix. Vous pouvez voir des exemples de timestamps dans les exemples de charges utiles ci-dessous.

Retour au haut de la page

Charges utiles

Il est possible que nous ajoutions des champs supplémentaires à ces charges utiles à l'avenir, afin que votre Webhook ne soulève pas d'erreur en présence d'un champ que vous n'attendiez pas. Notez que n'importe quel champ peut être défini comme null en plus du type indiqué.

Réponse au sondage

Nom de l'événement : survey_response

• id integer- Identifiant unique de la réponse à l'enquête.
• index integer - L'index de cette réponse à l'enquête dans l'enquête.
• api_id string - L'identifiant public (y compris l'UUID) se rapportant à cette réponse à l'enquête.
• response_url string - Le lien pour voir la réponse dans l'application Hotjar.
• site_id integer - L'identifiant unique du site Hotjar.
• survey_id integer - L'identifiant unique de l'enquête.
• survey_name string - Le nom de l'enquête.
• survey_url string - Le lien pour visualiser l'enquête dans l'application Hotjar.
• device string - Le type d'appareil utilisé pour soumettre la réponse à l'enquête. Il s'agit de "tablet", "mobile" ou "desktop".
• browser string - Le nom du type de navigateur utilisé pour soumettre la réponse à l'enquête.
• os string - Le nom du système d'exploitation utilisé pour soumettre la réponse à l'enquête.
• country_code string - Code du pays à partir duquel la réponse à l'enquête a été créée. Voir les codes de pays ISO 3166 pour une liste de ces codes.
• country_name string - Pays à partir duquel la réponse à l'enquête a été créée.
• hotjar_user_id string - L'identifiant Hotjar de l'utilisateur qui a soumis la réponse à l'enquête (un UUID).
• created_str string - La date et l'heure de création de la réponse à l'enquête sous la forme d'une chaîne ISO 8601.
• created_timestamp integer - Date et heure de création de la réponse à l'enquête sous forme d'horodatage UNIX.
• is_complete boolean - Drapeau indiquant si la réponse à l'enquête est complète ou non.
• recording_url string - Lien vers l'enregistrement qui contient la réponse à l'enquête, s'il existe.
• response_origin_url string - L'URL du site où l'utilisateur a soumis la réponse à l'enquête.
• window_width integer - La largeur de la fenêtre de l'utilisateur lors de la soumission de la réponse à l'enquête.
• window_height integer - Hauteur de la fenêtre de l'utilisateur lors de la soumission de la réponse à l'enquête.
• user_attributes object - Les attributs de l'utilisateur tels qu'ils sont fournis par l'API Identify de Hotjar. Chaque clé et chaque valeur de l'objet représentent les éléments suivants :
  • key string - Le nom de l'attribut de l'utilisateur.
  • value string/integer/float/boolean/datetime - La valeur de l'attribut utilisateur.
• questions array/list - Les questions et les réponses de l'enquête. Chaque élément comporte les champs suivants :
  • question_id integer - L'identifiant unique de la question.
  • question_text string - Le texte de la question.
  • question_type string - Le type de la question, qui correspondra à l'un des types suivants : reaction , long-text , short-text , single-option , option multiple , email , 1-5-évaluation , 1-7-évaluation , nps ou inconnu .
  • answers array/list - Les réponses à la question. Chaque réponse comporte les champs suivants :
    • answer string - La réponse donnée par l'utilisateur.
    • commentaire string - Le commentaire que l'utilisateur a laissé (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.

Message de test

Nom de l'événement : test_message

Cet événement est envoyé lors de l'envoi d'un message de test au Webhook.

exemple string - Toujours défini sur la chaîne "data".

Exemples de charges utiles

Réponse à un 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
}

Message de test

{
 "event" : "test_message",
 "version" : 1,
 "timestamp" : 473385600,
 "data" : {
 "sample" : "data"
 }
}

Retour au haut de la page