Articles in this section

Webhooks Reference

Available on Scale plan label plans.

 

Overview

Hotjar Webhooks allow you to be notified when an event occurs such as when a visitor to your website submits a new survey response. You set up a "webhook" (a URL) on your own website or on a partner company's website, share that webhook with Hotjar, and then receive event payloads when events occur. Webhooks are therefore a way to push data to your systems in real time.

In technical terms:

  1. You set up a webhook, usually on your own server/website, with a unique URL.
  2. Within the Hotjar interface you enter the webhook URL on a Survey or Feedback widget (by editing the Survey or Feedback widget).
  3. Hotjar then sends HTTP POST requests to your webhook URL whenever a new survey or feedback response is created.

Back to top

Why use Webhooks?

Webhooks complement the Hotjar Survey Responses API. While the API is most useful for bulk export (downloading), Webhooks are useful for immediately receiving survey and feedback responses as they are created. You should consider using Webhooks if:

  • You want to receive data immediately.
  • You want to send data to your systems, perhaps a data warehouse, without having to poll our API.
  • A partner offers an Integration with Hotjar via Webhooks.

Back to top

How Webhooks work

When an event occurs Hotjar will send a message to every configured Webhook:

  • The message is sent as a HTTP POST request to your webhook.
  • The request will be encoded as UTF-8.
  • The content type will be application/json.
  • The body of the request will therefore be a JSON object with the following properties:
    • event- string. The value of this property is the name of the event. At time of writing this will be survey_response, feedback_response or test_message.
    • version- integer. This property is reserved for future use, at present it will always be set to the number 1.
    • data- The value of this property will be a JSON object with the data of the event. The fields on the object are specific to each event (see below).

We send events as soon as possible after they occur; in practice you should receive a message within just a few seconds. In rare circumstances messages can be delayed, but each event includes the date and time they occurred so we recommend using that rather than the date and time your webhook receives a message.

Hotjar does not guarantee the order of messages received matches the order the events occurred. Some events contain an index parameter which can be used for ordering. 

Back to top

Webhook requirements

Your webhook must meet the following requirements:

  • The webhook must be HTTPS (TLS).
  • The server must respond within 10 seconds.
  • The server should respond with any HTTP 2XX status code (any HTTP status code between 200 and 299).
  • The server should accept any unexpected event type without returning an error.
  • The server should handle accidental duplicate messages. Although Hotjar makes every attempt to only ever send a message to your webhook once, we cannot guarantee it. Your webhook should therefore rely on the unique identifier in the message for deduplication.

Back to top

Retries

Hotjar will attempt to retry the sending of a webhook in the event of an error. Hotjar will retry up to six times, pausing between retries:

Retry attempt Delay before retrying
1 30 seconds
2 1 minute
3 2 minutes
4 5 minutes
5 10 minutes
6 20 minutes

 

Hotjar will retry sending until one of the following occurs:

  • The webhook responds with a 2XX status code (i.e. a successful response).
  • The webhook responds with a 410 status code (upon which Hotjar will delete the webhook from your survey or feedback widget).
  • Maximum 6 retries are reached.

Back to top

Payloads

Hotjar may add additional fields to these payloads in the future so your webhook should not raise an error when a field is present that you were not expecting. Note that any field can be set to null in addition to the stated type.

Feedback Response

Event name: feedback_response 

  • id integer- The unique identifier of the feedback response.
  • index integer - The index of this feedback response within the feedback widget.
  • feedback_response_url string - The link to view the response within the Hotjar app.
  • message string - The message the user entered.
  • email string - The e-mail address the user entered, if any.
  • emotion integer - The emotion/reaction score (1 to 5) the user selected.
  • created_str string - The date and time the feedback response was created as an ISO 8601 string.
  • created_timestamp integer - The date and time the feedback response was created as a UNIX Timestamp.
  • question string - The question on the feedback widget that the user answered.
  • site_id integer - The unique identifier of the Hotjar Site.
  • feedback_id integer - The unique identifier of the feedback widget.
  • feedback_name string - The name of the feedback widget.
  • feedback_url string - The link to view the feedback widget within the Hotjar app.
  • browser string - The name of the browser type used to submit the feedback response.
  • device string - The device type used to submit the feedback response. It will be "tablet", "mobile", or "desktop".
  • os string - The name of the operating system used to submit the feedback response.
  • country_name string - The country from which the feedback response was created.
  • country_code string - The country code from which the feedback response was created. See the ISO 3166 country codes for a list of these codes.
  • window_width integer - The width of the user's window when submitting the feedback response.
  • window_height integer - The height of the user's window when submitting the feedback response.
  • hotjar_user_id string - The Hotjar User ID for the user who submitted the feedback response (a UUID).

Survey Response

Event name: survey_response

  • id integer- The unique identifier of the survey response.
  • index integer - The index of this survey response within the survey.
  • api_id string - The public id (includes UUID) referring to this survey response.
  • response_url string - The link to view the response within the Hotjar app.
  • site_id integer - The unique identifier of the Hotjar Site.
  • survey_id integer - The unique identifier of the survey.
  • survey_name string - The name of the survey.
  • survey_url string - The link to view the survey within the Hotjar app.
  • device string - The device type used to submit the survey response. It will be "tablet", "mobile", or "desktop".
  • browser string - The name of the browser type used to submit the survey response.
  • os string - The name of the operating system used to submit the survey response.
  • country_code string - The country code from which the survey response was created. See the ISO 3166 country codes for a list of these codes.
  • country_name string - The country from which the survey response was created.
  • hotjar_user_id string - The Hotjar User ID for the user who submitted the survey response (a UUID).
  • created_str string - The date and time the survey response was created as an ISO 8601 string.
  • created_timestamp integer - The date and time the survey response was created as a UNIX Timestamp.
  • is_complete boolean - Flag indicating whether the survey response is completed or not.
  • recording_url string - The link to the Hotjar Recording that contains that survey response, if it exists.
  • response_origin_url string - The URL of the site where the user submitted the survey response.
  • window_width integer - The width of the user's window when submitting the survey response.
  • window_height integer - The height of the user's window when submitting the survey response.
  • user_attributes object - The user's attributes as provided by the Hotjar Identify API. Each key and value in the object represent the following:
    • key string - The name of the user attribute.
    • value string/integer/float/boolean/datetime - The value of the user attribute.
  • questions array/list - The questions and answers to the survey. Each element has the following fields:
    • question_id integer - The unique ID of the question.
    • question_text string - The text of the question.
    • question_type string - The type of the question. This will be one of reaction, long-text,  short-text,  single-option,  multiple-option,  email,  1-5-rating,  1-7-rating,  nps or  unknown.
    • answers array/list - The answers to the question. Each answer has the following fields:
      • answer string - The answer the user gave.
      • comment string - The comment the user left (if any).

Please note that questions that the user did not answer are not included in the payload.

 

Test Message

Event name: test_message

This event is sent when using the Hotjar App to send a test message to the webhook.

sample string - Always set to the string "data".

Site Downgrade

Event name: site_downgrade

This event is sent when the Hotjar Site's subscribed plan is downgraded and can no longer send messages to webhooks. Until the site upgrades again, no more messages will be sent.

site_id integer - The unique ID of the site that was downgraded.

Back to top

Related articles