Heap

Previous Next

Connect Heap

Heap Event Webhooks can send requests to a Squoosh endpoint. This connection prepares that endpoint and shows whether requests are arriving. It does not yet calibrate your AI shoppers.

Beta: surface stage

This connector has not been validated against a live account. Squoosh authenticates requests, checks their JSON structure, acknowledges them with 202 {"accepted": true}, and discards their contents. No event history, traffic distribution, conversion count or conversion rate is produced. Heap's own Event Webhooks feature is also in beta and has no uptime or deliverability guarantee.

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

Creating the connection generates a connection-specific ingest URL and a one-time shared secret. Endpoint ready means the endpoint is prepared, not that Heap data is connected or grounding a shopper pool.

An accepted request can produce a throttled Heap events arriving heartbeat in the sync log, at most once per hour per running server instance. The heartbeat contains no payload fields and is not an event count. Verification does not call Heap. Snapshot requests are unsupported at this stage.

Heap's documented export paths are Heap Connect, integrations and exports. This connector uses Event Webhooks; it does not query a Heap analytics API.

Connect Heap

Heap must enable Event Webhooks for your account. If Webhooks is missing, contact Heap through Get support and ask about availability of the beta. Enabling it is separate from creating the Squoosh endpoint. See Heap's webhook availability guidance.

  1. In Squoosh, open Integrations, choose Heap, and click Connect to generate the ingest URL and shared secret. Copy the secret immediately; Squoosh shows it once.
  2. In Heap, open Integrations > Directory > Webhooks > New Webhook. Some accounts expose a webhooks console in the left sidebar.
  3. In URL, paste the complete Squoosh URL, including ?connection=<connectionId>. Its path is /api/integrations/heap/ingest. Use POST.
  4. In HTTP Headers, add the header name x-squoosh-heap-secret and set its value to the shared secret. Do not put the secret in the URL or JSON body.
  5. In Data to Send (JSON), use the template below. Keep event as a constant naming the triggering event. Replace angle-bracket placeholders using the Heap event/user property picker, and remove optional keys whose properties are unavailable.
  6. In Triggering Events, choose the labeled or custom events you want Heap to send and save the webhook. Ordinary matching activity can produce a Squoosh heartbeat; Squoosh does not send a fabricated Track event to test the connection.
{
  "event": "purchase",
  "session_id": "<Session ID>",
  "user_id": "<User ID>",
  "time": "<Time>",
  "device_type": "<Device Type>",
  "country": "<Country>",
  "referrer": "<Referrer>",
  "utm_source": "<UTM Source>",
  "utm_medium": "<UTM Medium>",
  "landing_page": "<Landing Page>"
}

This is a Squoosh-defined template, not a fixed Heap schema or Heap interpolation syntax. Heap lets you name every key. The template is flat; Heap supports at most one nested object level and no arrays. The endpoint validates that structure without requiring specific keys or Content-Type. Availability of the session properties above inside the webhook picker has not been verified; a constant-only object such as {"event":"purchase"} is sufficient for endpoint readiness.

The documented setup uses only x-squoosh-heap-secret. It does not accept Basic authentication, bearer tokens or signatures. An empty body is accepted; nonempty bodies must follow the JSON structure below. Heap documents basic header authentication, not an HMAC signature scheme.

What Squoosh reads and never reads

Item Current behavior
Connection identity and shared secret Resolves an active Heap connection and compares the presented secret with its encrypted credential.
Webhook body Reads for size and JSON structure, then discards it. No payload values enter logs or the sync history.
Arrival status Writes a throttled heartbeat or actionable authentication error.
Device, geography and traffic mix No distributions are computed from webhook arrivals.
Conversion activity No conversion counts or rates are computed.
Heap account APIs No API calls, Track writes, user deletion requests or Privacy API credentials.

Use exported data for calibration

For customer-provided numbers today, use CSV / Excel import. Export the relevant Heap chart where your plan permits it, then prepare the import format shown on that page. Imported figures are self-reported. Heap documents an export ceiling of up to 100,000 rows per metric; this is an export limit, not proof that any particular export was truncated. CSV export availability depends on your plan. See Heap's CSV export limits.

If you have Heap Connect and a supported Squoosh warehouse connector available, create a customer-owned SQUOOSH_CALIBRATION view over your synced Heap tables and connect through the warehouse. Heap's sessions data includes device_type, country, utm_* and referrer; the customer must define traffic-channel groups and a consistent session population. A conversion rate needs a real session denominator and conversions from the same population and window. Server-side sessions do not appear in Heap's sessions table, so server event arrivals alone cannot supply that denominator. Follow the warehouse connector's view and freshness requirements. See Heap Connect's data schema.

Limits and caveats

  • Squoosh accepts at most 1 MiB per request, measured in UTF-8 bytes. Oversize requests receive 413 {"error":"payload_too_large"}.
  • The shared Squoosh rate bucket allows 6,000 requests per 60 seconds per authenticated connection. A limit response is 429 {"error":"rate_limited"} with Retry-After. The limiter fails open if its backing service is unavailable.
  • Malformed JSON, arrays, excess nesting and broken body streams receive 400 {"error":"invalid_body"}. Authentication occurs before the body read, except for the early declared-length rejection.
  • Missing, invalid or unreadable secrets, unavailable connections, and connections belonging to other providers receive the same 401 {"error":"Unauthorized"} response.
  • Heap does not document a webhook acknowledgement deadline, retry/backoff policy or outbound Content-Type guarantee. Squoosh makes no claim that Heap retries a refusal.
  • Heap may shut down webhooks for scaling reasons during beta. An absent heartbeat can mean no matching activity, incomplete setup or a delivery gap; it does not establish an authentication failure.
  • This stage provides no replay detection, deduplication, backfill or retained event data. Receiving a request never establishes complete analytics coverage.

Troubleshooting

Problem What to do
Webhooks is missing in Heap Ask Heap support whether Event Webhooks can be enabled for your account.
Endpoint ready but no heartbeat Confirm the URL and Triggering Events, then check whether matching activity occurred. Check Heap-side availability and setup; no heartbeat alone does not prove a bad secret.
401 Unauthorized Confirm the full Heap ingest URL, the active connection and the x-squoosh-heap-secret header. Reconnect if the one-time secret was lost or rotated.
400 invalid_body Leave the optional body empty or send a JSON object. Remove arrays and objects nested more than one level deep. Check for malformed JSON or an interrupted delivery.
413 payload_too_large Reduce Data to Send below 1 MiB.
429 rate_limited Reduce matching webhook volume. The response supplies Retry-After; Heap's retry behavior is undocumented.
Requests arrive but no calibration appears Expected at surface stage. Use the file importer or a supported warehouse connection for calibration data.
FullStory Hotjar