Connect Hotjar¶

Hotjar can send selected recording and survey-response webhooks to Squoosh. This connection is a receiving surface only. It does not calibrate AI shoppers or provide traffic distributions or conversion rates.

This connector has not been validated against a live account. Saving a connection does not verify the key, plan permissions, or event delivery.

Saving creates an Endpoint ready / Awaiting delivery connection. A current-key authenticated delivery heartbeat establishes transport health. Checking status cannot verify a key, and rotating the key requires a new delivery. Payloads remain discarded and no calibration numbers are produced.

What the connection does¶

The endpoint checks a delivery's signature, validates its envelope, acknowledges eligible messages, and discards the event payload. A periodic sync-log heartbeat records that authenticated messages are arriving. No recording or survey-response content is retained.

Hotjar recordings are sampled and filtered by the saved Recording Segment. Survey respondents are a self-selected population. Neither describes all your traffic, and neither supplies a session denominator for a conversion rate. Device, geography, and referrer fields therefore do not change the shopper pool.

Connect Hotjar¶

Hotjar documents recording webhooks for Observe Scale and survey webhooks for Ask Scale. Confirm that Webhooks is available for your site.

1. In Hotjar, open the site's Webhooks Integration settings and choose View Webhook key. The settings address follows https://insights.hotjar.com/settings/integrations/sites/<site-id>/webhooks.
2. In Squoosh, open Integrations, choose Hotjar, and enter the Webhook signing key. One Hotjar site is supported per Squoosh workspace. Saving another site’s key replaces the existing connection’s key. This is a Hotjar-issued key, not a REST API client secret or a Squoosh-generated key.
3. Copy the HTTPS ingest URL Squoosh provides. Keep the complete ?connection=... query parameter. The path is /api/integrations/hotjar/ingest.
4. For recordings, open your saved Recording Segment, select its three-dot menu, and choose Webhook. For survey responses, configure the webhook on the relevant Survey. Paste the Squoosh URL as the destination.
5. Send Hotjar's test message and check Squoosh's sync log for an arrival heartbeat. Hotjar supplies the com-hotjar-signature header automatically; do not paste your signing key into a custom authentication header.

See the official Webhooks Reference for Hotjar's setup and delivery contract.

What Squoosh reads and never reads¶

Limits and caveats¶

• No backfill or snapshot. This connection receives future deliveries only and never supplies a calibration snapshot.
• Delivery timing. Hotjar requires a 2xx response within ten seconds. Squoosh uses an eight-second handler budget and defers heartbeat writes until after acknowledgement. Infrastructure failures receive a retryable response; the endpoint never returns 410, which would make Hotjar delete the webhook.
• Retries. Hotjar documents up to six retries after 30 seconds, 1 minute, 2 minutes, 5 minutes, 10 minutes and 20 minutes. Duplicates and out-of-order deliveries are possible.
• Replay checks. A valid signature is required before timestamp inspection. Messages more than five minutes old, more than five minutes in the future, or lacking a usable timestamp are acknowledged and discarded. Recording and survey messages with a null or missing ID cannot establish a unique arrival and are also discarded.
• Heartbeat throttling is approximate. Successful heartbeats are limited to one per connection and credential generation per hour in one running server instance. A duplicate delivery may establish proof for a replacement key or retry a failed heartbeat write. Restarts and separate instances can repeat telemetry. No exact event count is stored or reported.
• Signature encoding. Hotjar documents the algorithm but not the header encoding. Squoosh checks both hex and base64 encodings; a live test message is still needed to confirm actual delivery behavior.
• Body and rate limits. Squoosh accepts bodies up to 1 MiB and applies the shared ingest limit of 6,000 authenticated requests per minute per connection. Rate-limited responses include Retry-After.
• Site downgrade. An authenticated site_downgrade is acknowledged with a permission warning in operational diagnostics. A warning entry also appears in the customer sync log, at most once per hour per worker.
• Account migration. Webhook availability after a move to Contentsquare depends on the destination plan and account state. Hotjar's migration FAQ lists webhooks as unsupported on Contentsquare Growth and describes an option to postpone migration. See the migration FAQ.

Troubleshooting¶

Related¶

• Connect Google Analytics and Connect Matomo for traffic calibration.
• Connect a CSV / Excel import for your own aggregate counts.
• Connect Segment for another inbound event surface.
• Hotjar API Reference for the separate REST survey capabilities.