Referência de Webhooks

• Visão geral
• Por que usar Webhooks?
• Como os Webhooks funcionam
  • Requisitos do Webhook
  • Tentativas
  • Assinaturas e prevenção de repetições
  • Cargas

Visão geral

Os Webhooks do Hotjar permitem que você seja notificado quando um evento ocorre, como quando um visitante do seu site envia uma nova resposta de pesquisa. Você configura um "webhook" (uma URL) no seu próprio site ou no site de uma empresa parceira, compartilha esse webhook com o Hotjar e, em seguida, recebe cargas de eventos quando os eventos ocorrem. Portanto, os Webhooks são uma maneira de enviar dados para seus sistemas em tempo real.

Em termos técnicos:

1. Você configura um webhook, geralmente no seu próprio servidor/site, com uma URL única.
2. Dentro da interface do Hotjar, você insere a URL do webhook em um widget de Pesquisa, widget de Feedback ou um Segmento de Gravação.
3. O Hotjar então envia solicitações POST HTTP para a URL do seu webhook sempre que uma nova pesquisa ou resposta de feedback é criada, ou quando uma nova gravação que corresponde ao seu segmento de gravação é criada.

Voltar ao topo

Por que usar Webhooks?

Os Webhooks complementam a API do Hotjar. Enquanto a API é mais útil para exportação em massa (download), os Webhooks são úteis para receber imediatamente respostas de pesquisas e feedback, ou gravações com base em segmentos de gravação conforme são criadas. Você deve considerar o uso de Webhooks se:

• Você deseja receber dados imediatamente.
• Você deseja enviar dados para seus sistemas, talvez um data warehouse, sem precisar consultar nossa API.
• Um parceiro oferece uma integração com o Hotjar via Webhooks.

Voltar ao topo

Como os Webhooks funcionam

Quando um evento ocorre, o Hotjar enviará uma mensagem para cada Webhook configurado:

• A mensagem é enviada como uma solicitação POST HTTP para o seu webhook.
• A solicitação será codificada como UTF-8.
• O tipo de conteúdo será application/json.
• O corpo da solicitação será, portanto, um objeto JSON com as seguintes propriedades:
  • event- string. O valor desta propriedade é o nome do evento. No momento da escrita, será survey_response, feedback_response, recording ou test_message.
  • version- inteiro. Esta propriedade está reservada para uso futuro, atualmente sempre será definida como o número 1.
  • data- O valor desta propriedade será um objeto JSON com os dados do evento. Os campos do objeto são específicos para cada evento (veja abaixo).

Enviamos os eventos assim que possível após sua ocorrência; na prática, você deve receber uma mensagem em apenas alguns segundos. Em circunstâncias raras, as mensagens podem ser atrasadas, mas cada evento inclui a data e hora em que ocorreram, então recomendamos usar isso em vez da data e hora em que seu webhook recebe uma mensagem.

O Hotjar não garante que a ordem das mensagens recebidas corresponda à ordem em que os eventos ocorreram. Alguns eventos contêm um parâmetro index que pode ser usado para ordenação.

Voltar ao topo

Requisitos do Webhook

Seu webhook deve atender aos seguintes requisitos:

• O webhook deve ser HTTPS (TLS).
• O servidor deve responder dentro de 10 segundos.
• O servidor deve responder com qualquer código de status HTTP 2XX (qualquer código de status HTTP entre 200 e 299).
• O servidor deve aceitar qualquer tipo de evento inesperado sem retornar um erro.
• O servidor deve lidar com mensagens duplicadas acidentais. Embora o Hotjar faça todo o esforço para enviar uma mensagem para seu webhook apenas uma vez, não podemos garantir. Portanto, seu webhook deve confiar no identificador único na mensagem para deduplicação.

Voltar ao topo

Tentativas

O Hotjar tentará reenviar o envio de um webhook no caso de um erro. O Hotjar tentará até seis vezes, pausando entre as tentativas:

O Hotjar tentará reenviar o envio até que ocorra uma das seguintes situações:

• O webhook responde com um código de status 2XX (ou seja, uma resposta bem-sucedida).
• O webhook responde com um código de status 410 (no qual o Hotjar excluirá o webhook do seu widget de pesquisa, widget de feedback ou segmento de gravação).
• O máximo de 6 tentativas é atingido.

Voltar ao topo

Assinaturas e prevenção de replay

Os webhooks do Hotjar usam duas técnicas de segurança para garantir que você possa verificar se os payloads que você recebe são realmente do Hotjar:

• Todos os payloads enviados para seus webhooks são assinados por HMAC; é altamente recomendável que você verifique a assinatura para ter certeza de que os dados realmente vieram do Hotjar
• Todos os payloads incluem um carimbo de data/hora para que você possa verificar se os dados foram enviados pelo Hotjar nos últimos minutos. Isso permite que você mitigue ataques de replay, pois você pode ter certeza de que o Hotjar enviou esses dados para você nos últimos minutos.

Verificando a assinatura do payload

A assinatura é enviada para seu webhook como um cabeçalho personalizado chamado com-hotjar-signature. Para verificar se a assinatura é válida, você precisa:

1. Gerar uma assinatura a partir do payload que você recebeu
2. Verificar se sua assinatura gerada corresponde à assinatura no cabeçalho

Você pode gerar uma assinatura usando HMAC-SHA3-256, o payload (como bytes) e uma chave de assinatura. Para obter a chave de assinatura para o seu site Hotjar, abra as Configurações de Integração de Webhooks dentro do aplicativo Hotjar e clique em "Visualizar chave do webhook".

Depois de gerar uma assinatura, você pode compará-la com a assinatura enviada no cabeçalho com-hotjar-signature. Se os dois valores corresponderem, a assinatura foi validada com sucesso; se não corresponderem, você deve descartar o payload e não agir sobre ele.

Protegendo contra ataques de replay

A assinatura HMAC permite que você verifique que o Hotjar criou o payload do webhook, mas um atacante poderia enviar o mesmo payload novamente (e novamente!) e a verificação da assinatura seria bem-sucedida. Para se proteger contra esses "ataques de replay", também enviamos um carimbo de data/hora dentro do payload; se a data e hora especificadas no carimbo de data/hora forem muito antigas (sugerimos mais de 5 minutos no passado), você deve descartar o payload.

Para verificar o carimbo de data/hora, você deve primeiro verificar a assinatura HMAC, conforme descrito acima, antes de verificar o carimbo de data/hora, pois um atacante poderia simplesmente enviar um carimbo de data/hora válido dentro de um payload. O carimbo de data/hora é um carimbo de data/hora UNIX, o que significa que é o número de segundos desde o início do Unix. Você pode ver exemplos de carimbos de data/hora nos payloads de exemplo abaixo.

Voltar ao topo

Payloads

O Hotjar pode adicionar campos adicionais a esses payloads no futuro, portanto, seu webhook não deve gerar um erro quando um campo estiver presente e você não estiver esperando. Observe que qualquer campo pode ser definido como nulo, além do tipo declarado.

Resposta de Feedback

Nome do evento: feedback_response 

• ID inteiro - O identificador único da resposta de feedback.
• índice inteiro - O índice desta resposta de feedback dentro do widget de feedback.
• feedback_response_url string - O link para visualizar a resposta no aplicativo Hotjar.
• mensagem string - A mensagem inserida pelo usuário.
• e-mail string - O endereço de e-mail inserido pelo usuário, se houver.
• emoção inteiro - O score de emoção/reação (1 a 5) selecionado pelo usuário.
• criado_str string - A data e hora em que a resposta de feedback foi criada como uma string ISO 8601.
• criado_timestamp inteiro - A data e hora em que a resposta de feedback foi criada como um carimbo de data/hora UNIX.
• pergunta string - A pergunta no widget de feedback que o usuário respondeu.
• ID_site inteiro - O identificador único do Site Hotjar.
• ID_feedback inteiro - O identificador único do widget de feedback.
• nome_feedback string - O nome do widget de feedback.
• URL_feedback string - O link para visualizar o widget de feedback no aplicativo Hotjar.
• navegador string - O nome do tipo de navegador usado para enviar a resposta de feedback.
• dispositivo string - O tipo de dispositivo usado para enviar a resposta de feedback. Será "tablet", "mobile" ou "desktop".
• SO string - O nome do sistema operacional usado para enviar a resposta de feedback.
• nome_país string - O país de onde a resposta de feedback foi criada.
• código_país string - O código do país de onde a resposta de feedback foi criada. Consulte os códigos de país ISO 3166 para obter uma lista desses códigos.
• largura_janela inteiro - A largura da janela do usuário ao enviar a resposta de feedback.
• altura_janela inteiro - A altura da janela do usuário ao enviar a resposta de feedback.
• ID_usuário_hotjar string - O ID de usuário Hotjar para o usuário que enviou a resposta de feedback (um UUID).

Resposta da Pesquisa

Nome do evento: resposta_pesquisa

• ID número inteiro - O identificador único da resposta da pesquisa.
• índice número inteiro - O índice desta resposta da pesquisa dentro da pesquisa.
• api_id string - O ID público (inclui UUID) referente a esta resposta da pesquisa.
• response_url string - O link para visualizar a resposta dentro do aplicativo Hotjar.
• site_id número inteiro - O identificador único do Site Hotjar.
• survey_id número inteiro - O identificador único da pesquisa.
• survey_name string - O nome da pesquisa.
• survey_url string - O link para visualizar a pesquisa dentro do aplicativo Hotjar.
• dispositivo string - O tipo de dispositivo usado para enviar a resposta da pesquisa. Será "tablet", "mobile" ou "desktop".
• navegador string - O nome do tipo de navegador usado para enviar a resposta da pesquisa.
• so string - O nome do sistema operacional usado para enviar a resposta da pesquisa.
• código_do_país string - O código do país de onde a resposta da pesquisa foi criada. Consulte os códigos de país ISO 3166 para obter uma lista desses códigos.
• nome_do_país string - O país de onde a resposta da pesquisa foi criada.
• ID_de_usuário_Hotjar string - O ID de usuário Hotjar para o usuário que enviou a resposta da pesquisa (um UUID).
• criado_str string - A data e hora em que a resposta da pesquisa foi criada como uma string ISO 8601.
• criado_timestamp número inteiro - A data e hora em que a resposta da pesquisa foi criada como um carimbo de data/hora UNIX.
• está_completo boolean - Indica se a resposta da pesquisa está concluída ou não.
• url_de_gravação string - O link para a Gravação Hotjar que contém essa resposta da pesquisa, se existir.
• url_de_origem_da_resposta string - O URL do site onde o usuário enviou a resposta da pesquisa.
• largura_da_janela número inteiro - A largura da janela do usuário ao enviar a resposta da pesquisa.
• altura_da_janela número inteiro - A altura da janela do usuário ao enviar a resposta da pesquisa.
• atributos_do_usuário objeto - Os atributos do usuário fornecidos pela API de identificação do Hotjar. Cada chave e valor no objeto representam o seguinte:
  • chave string - O nome do atributo do usuário.
  • valor string/número inteiro/número decimal/booleano/data e hora - O valor do atributo do usuário.
• perguntas array/list - As perguntas e respostas da pesquisa. Cada elemento possui os seguintes campos:
  • id_pergunta número inteiro - O ID único da pergunta.
  • texto_pergunta texto - O texto da pergunta.
  • tipo_pergunta texto - O tipo de pergunta. Isso será um dos reação, texto-longo,  texto-curto,  opção-única,  opção-múltipla,  e-mail,  avaliação-1-5,  avaliação-1-7,  nps ou  desconhecido. 
  • respostas array/list - As respostas para a pergunta. Cada resposta possui os seguintes campos:
    • resposta texto - A resposta que o usuário deu.
    • comentário texto - O comentário que o usuário deixou (se houver).

Por favor, observe que as perguntas que o usuário não respondeu não estão incluídas na carga útil.

Gravação

Nome do evento: gravação

• ID inteiro - O identificador único da gravação.
• site_id inteiro - O identificador único do Site Hotjar.
• country_name string - O país de onde ocorreu a sessão que foi gravada.
• country_code string - O código do país de onde ocorreu a sessão que foi gravada. Consulte os códigos de país ISO 3166 para obter uma lista desses códigos.
• hotjar_user_id string - O ID de usuário Hotjar do usuário cuja sessão foi gravada (um UUID).
• device string - O tipo de dispositivo usado pelo usuário cuja sessão foi gravada. Será "tablet", "mobile" ou "desktop".
• browser string - O nome do tipo de navegador usado pelo usuário cuja sessão foi gravada.
• browser_version string - A versão do navegador usada pelo usuário cuja sessão foi gravada.
• os string - O nome do sistema operacional usado pelo usuário cuja sessão foi gravada.
• os_version string - A versão do sistema operacional usado pelo usuário cuja sessão foi gravada.
• action_count inteiro - O número de ações realizadas pelo usuário na sessão.
• rageclick_occurred booleano - Um clique de raiva ocorreu durante a sessão que foi gravada.
• uturn_occurred booleano - Um retorno rápido ocorreu durante a sessão que foi gravada.
• created_str string - A data e hora em que a gravação foi criada como uma string ISO 8601.
• created_timestamp inteiro - A data e hora em que a gravação foi criada como um carimbo de data/hora UNIX.
• referrer string - A página em que o usuário estava antes de iniciar sua sessão no Hotjar, se disponível.
• window_width inteiro - A largura da janela do usuário quando a sessão foi gravada.
• window_height inteiro - A altura da janela do usuário quando a sessão foi gravada.
• duration inteiro - O comprimento da sessão gravada em milissegundos.
• relevance_score inteiro - O score de relevância é baseado em diversos fatores para determinar o quão útil uma gravação provavelmente será. Esses fatores incluem duração da sessão, número de páginas visitadas, número de ações, cliques de raiva, retornos rápidos, erros do console, digitação, eventos enviados via JavaScript, e interação com formulários.
• page_urls array/lista - A lista de URLs das páginas visitadas durante a sessão.
• event_names array/lista - Os eventos que ocorreram durante a sessão gravada conforme fornecido pela API de eventos Hotjar.
• landing_page_url string - A página em que o usuário estava quando sua sessão no Hotjar começou.
• exit_page_url string - A página em que o usuário estava quando sua sessão no Hotjar terminou.
• recording_url string - O link para visualizar a gravação dentro do aplicativo Hotjar.
• user_attributes object - Os atributos do usuário fornecidos pela API de identificação do Hotjar. Cada chave e valor no objeto representam o seguinte:
  • key string - O nome do atributo do usuário.
  • value string/integer/float/boolean/datetime - O valor do atributo do usuário.

Mensagem de Teste

Nome do evento: test_message

Este evento é enviado ao usar o aplicativo Hotjar para enviar uma mensagem de teste para o webhook.

amostra string - Sempre definido como a string "dados".

Downgrade do Site

Nome do evento: site_downgrade

Este evento é enviado quando o plano assinado do Site Hotjar é reduzido e não pode mais enviar mensagens para webhooks. Até que o site faça um upgrade novamente, nenhuma outra mensagem será enviada.

site_id inteiro - O ID único do site que foi reduzido.

Exemplos de payloads

Resposta de Feedback

{
  "event": "feedback_response",
  "data": {
    "id": 32,
    "index": 1,
    "feedback_response_url": "https://fictitious.feedback-response.com/14/32",
    "message": "Mensagem padrão",
    "email": null,
    "emotion": 4,
    "created_str": "2023-06-07T11:26:42.287596Z",
    "created_timestamp": 1686137202,
    "question": "Esta é a pergunta inicial",
    "site_id": 42,
    "feedback_id": 42,
    "feedback_name": "Feedback Padrão",
    "feedback_url": "https://insights.hotjar.com/url/goes/here",
    "navegador": "Chrome",
    "dispositivo": "Desktop",
    "sistema_operacional": "Windows",
    "nome_do_país": "Malta",
    "código_do_país": "MT",
    "largura_da_janela": 1024,
    "altura_da_janela": 768,
    "ID_do_hotjar_user": "dbbc63df-1b09-4631-a837-255e162788c0"
  },
  "versão": 1,
  "timestamp": 473385600
}

Resposta da Pesquisa

{
  "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": "example@example.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
}

Gravação

{
  "event": "recording",
  "data": {
    "id": 42,
    "site_id":14,
    "country_name":"Malta",
    "country_code":"MT",
    "hotjar_user_id":"90fc1180-90b4-463c-9d1f-3415477f0168",
    "device":"desktop",
    "browser":"Chrome",
    "browser_version":"51.0.2704",
    "os":"Mac OS X",
    "os_version":"10.11.2",
    "action_count":42,
    "user_attributes":{
      "test_ua_one":"value",
      "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":[
      "Pricing Element Viewed",
      "Clicked Login Button"
    ],
    "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
}

Mensagem de Teste

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

Downgrade do Site

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

Voltar ao topo