Referência de Webhooks

• Visão geral
• Por que usar Webhooks?
• Como funcionam os Webhooks
• Requisitos do Webhook
• Tentativas
• Cargas úteis

---

 

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) em seu próprio site ou no site de uma empresa parceira, compartilha esse webhook com o Hotjar e, em seguida, recebe cargas úteis de eventos quando os eventos ocorrem. Os Webhooks são, portanto, uma maneira de enviar dados para seus sistemas em tempo real.

Em termos técnicos:

1. Você configura um webhook, geralmente em 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 ou Feedback (editando o widget de Pesquisa ou Feedback).
3. O Hotjar então envia solicitações HTTP POST para a URL do seu webhook sempre que uma nova resposta de pesquisa ou feedback é criada.

Voltar ao topo

Por que usar Webhooks?

Os Webhooks complementam a API de Respostas de Pesquisa do Hotjar. Enquanto a API é mais útil para exportação em massa (download), os Webhooks são úteis para receber imediatamente respostas de pesquisa e feedback à medida que são criadas. Você deve considerar o uso de Webhooks se:

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

Voltar ao topo

Como funcionam os Webhooks

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

• A mensagem é enviada como uma solicitação HTTP POST 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 ou test_message.
  • version - inteiro. Esta propriedade é reservada para uso futuro, no momento 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 eventos o mais rápido possível após ocorrerem; 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 a hora em que ocorreram, por isso 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 dos eventos ocorridos. 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 acidentalmente. Embora a Hotjar faça todos os esforços para enviar uma mensagem ao seu webhook apenas uma vez, não podemos garantir isso. Seu webhook deve, portanto, confiar no identificador único na mensagem para desduplicação.

Voltar ao topo

Tentativas

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

Tentativa de reenvio	Atraso antes de tentar novamente
1	30 segundos
2	1 minuto
3	2 minutos
4	5 minutos
5	10 minutos
6	20 minutos

 

A Hotjar continuará tentando enviar até que uma das seguintes situações ocorra:

• 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 (após o qual a Hotjar excluirá o webhook de sua pesquisa ou widget de feedback).
• O máximo de 6 tentativas é atingido.

Voltar ao topo

Cargas úteis

A Hotjar pode adicionar campos adicionais a essas cargas úteis no futuro, então seu webhook não deve gerar um erro quando um campo estiver presente que você não estava esperando. Note que qualquer campo pode ser definido como nulo além do tipo declarado.

Resposta de Feedback

Nome do evento: feedback_response 

• id integer - O identificador único da resposta do feedback.
• index integer - O índice desta resposta de feedback dentro do widget de feedback.
• feedback_response_url string - O link para visualizar a resposta dentro do aplicativo Hotjar.
• message string - A mensagem que o usuário inseriu.
• email string - O endereço de e-mail que o usuário inseriu, se houver.
• emotion integer - A pontuação da emoção/reação (1 a 5) que o usuário selecionou.
• created_str string - A data e a hora em que a resposta do feedback foi criada como uma string ISO 8601.
• created_timestamp integer - A data e a hora em que a resposta do feedback foi criada como um Timestamp UNIX.
• question string - A pergunta no widget de feedback que o usuário respondeu.
• site_id integer - O identificador único do Site Hotjar.
• feedback_id integer - O identificador único do widget de feedback.
• feedback_name string - O nome do widget de feedback.
• feedback_url string - O link para visualizar o widget de feedback dentro do aplicativo Hotjar.
• browser string - O nome do tipo de navegador usado para enviar a resposta do feedback.
• device string - O tipo de dispositivo usado para enviar a resposta do feedback. Será "tablet", "mobile" ou "desktop".
• os string - O nome do sistema operacional usado para enviar a resposta do feedback.
• country_name string - O país de onde a resposta do feedback foi criada.
• country_code string - O código do país de onde a resposta do feedback foi criada. Veja os códigos de país ISO 3166 para uma lista desses códigos.
• window_width integer - A largura da janela do usuário ao enviar a resposta do feedback.
• window_height integer - A altura da janela do usuário ao enviar a resposta do feedback.
• hotjar_user_id string - O ID do usuário Hotjar para o usuário que enviou a resposta do feedback (um UUID).

Resposta da Pesquisa

Nome do evento: survey_response

• id integer- O identificador único da resposta à pesquisa.
• index integer - O índice desta resposta à pesquisa dentro da pesquisa.
• api_id string - O id público (inclui UUID) referente a esta resposta à pesquisa.
• response_url string - O link para visualizar a resposta dentro do aplicativo Hotjar.
• site_id integer - O identificador único do Site Hotjar.
• survey_id integer - 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.
• device string - O tipo de dispositivo usado para enviar a resposta à pesquisa. Será "tablet", "mobile" ou "desktop".
• browser string - O nome do tipo de navegador usado para enviar a resposta à pesquisa.
• os string - O nome do sistema operacional usado para enviar a resposta à pesquisa.
• country_code string - O código do país a partir do qual a resposta à pesquisa foi criada. Veja os códigos de país ISO 3166 para uma lista desses códigos.
• country_name string - O país a partir do qual a resposta à pesquisa foi criada.
• hotjar_user_id string - O ID do Usuário Hotjar para o usuário que enviou a resposta à pesquisa (um UUID).
• created_str string - A data e hora em que a resposta à pesquisa foi criada como uma string ISO 8601.
• created_timestamp integer - A data e hora em que a resposta à pesquisa foi criada como um Timestamp UNIX.
• is_complete boolean - Indicador de se a resposta à pesquisa está completa ou não.
• recording_url string - O link para a Gravação Hotjar que contém essa resposta à pesquisa, se existir.
• response_origin_url string - A URL do site onde o usuário enviou a resposta à pesquisa.
• window_width integer - A largura da janela do usuário ao enviar a resposta à pesquisa.
• window_height integer - A altura da janela do usuário ao enviar a resposta à pesquisa.
• user_attributes object - Os atributos do usuário conforme fornecidos pela API de Identificação 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.
• questions array/lista - As perguntas e respostas da pesquisa. Cada elemento possui os seguintes campos:
  • question_id integer - O ID único da pergunta.
  • question_text string - O texto da pergunta.
  • question_type string - O tipo da pergunta. Este será um dos seguintes reaction, long-text,  short-text,  single-option,  multiple-option,  email,  1-5-rating,  1-7-rating,  nps ou  unknown.
  • answers array/lista - As respostas para a pergunta. Cada resposta possui os seguintes campos:
    • answer string - A resposta que o usuário deu.
    • comment string - O comentário que o usuário deixou (se houver).

Observe que as perguntas que o usuário não respondeu não estão incluídas no payload.

 

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.

sample string - Sempre definido para a string "data".

Downgrade do Site

Nome do evento: site_downgrade

Este evento é enviado quando o plano assinado do Site Hotjar é rebaixado e não pode mais enviar mensagens para webhooks. Até que o site seja atualizado novamente, nenhuma outra mensagem será enviada.

site_id integer - O ID único do site que foi rebaixado.

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",
    "browser": "Chrome",
    "device": "Desktop",
    "os": "Windows",
    "country_name": "Malta",
    "country_code": "MT",
    "window_width": 1024,
    "window_height": 768,
    "hotjar_user_id": "dbbc63df-1b09-4631-a837-255e162788c0"
  },
  "version": 1
}

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": "Pesquisa de teste",
    "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": "Pergunta 1",
        "question_type": "short-text",
        "answers": [
          {
            "answer": "A resposta para a pergunta 1 vai aqui",
            "comment": null
          }
        ]
      },
      {
        "question_id": 2,
        "questiom_text": "Pergunta 2",
        "question_type": "long-text",
        "answers": [
          {
            "answer": "A resposta para a pergunta 2 vai aqui\n\n nova linha",
            "comment": null
          }
        ]
      },
      {
        "question_id": 3,
        "questiom_text": "Pergunta 3",
        "question_type": "email",
        "answers": [
          {
            "answer": "support@hotjar.com",
            "comment": null
          }
        ]
      },
      {
        "question_id": 4,
        "questiom_text": "Pergunta 4",
        "question_type": "single-option",
        "answers": [
          {
            "answer": "botão de rádio?",
            "comment": "comentário"
          }
        ]
      },
      {
        "question_id": 5,
        "questiom_text": "Pergunta 5",
        "question_type": "multiple-option",
        "answers": [
          {
            "answer": "isto",
            "comment": "comentário"
          },
          {
            "answer": "aquilo",
            "comment": "comentário"
          }
        ]
      },
      {
        "question_id": 6,
        "questiom_text": "Pergunta 6",
        "question_type": "1-5-rating",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 7,
        "questiom_text": "Pergunta 7",
        "question_type": "1-7-rating",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 8,
        "questiom_text": "Pergunta 8",
        "question_type": "nps",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 9,
        "questiom_text": "Pergunta 9",
        "question_type": "reaction",
        "answers": [
          {
            "answer": "3",
            "comment": null
          }
        ]
      },
      {
        "question_id": 10,
        "questiom_text": "Pergunta 10",
        "question_type": "short-text",
        "answers": [
          {
            "answer": "",
            "comment": null
          }
        ]
      }
    ]
  },
  "version": 1
}

Mensagem de Teste

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

Downgrade do Site

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

Voltar ao topo