Skip to main content

Heap

Heap is a digital analytics platform that automatically captures user interactions on websites and mobile apps. Unlike traditional analytics that require manual event tagging, Heap captures everything automatically and provides server-side APIs to enrich that data with custom events, user properties, and account-level information for comprehensive product analytics.

Authentication Types​

Heap supports 1 authentication method:

  • API Key - Use your Heap App ID and API Key for server-side authentication.
    • Pros: Simple setup, works for server-side integrations, programmatic access
    • Cons: Single credential shared across all users, requires secure storage
    • Best for: Server-side event tracking, backend integrations, data enrichment workflows

General Settings​

Before using the connector, you need to configure:

  • App ID - Your Heap environment ID (found in the Projects page)
    • This is a numeric identifier like "123456789"
    • Used for all API requests to identify your Heap environment
  • Data Center - Select your Heap data center location (US or EU)
    • US: Data stored in the United States (heapanalytics.com)
    • EU: Data stored in the European Union (c.eu.heap-api.com)
    • Check your Heap account settings to determine which data center you're using

Setting up API Key​

To use Heap with Webrix, you need your App ID and API Key:

1. Get Your App ID​

  1. Log in to your Heap account at heapanalytics.com

  2. Click on Settings in the left sidebar

  3. Navigate to Projects

  4. Find your environment (e.g., "Production") and copy the App ID

    tip

    Your App ID is a numeric identifier like "123456789". You'll need this for the API credentials.

  5. IMPORTANT: For the deletion API, you must use your Main Production environment App ID. Using other environment IDs will result in Unauthorized errors.

2. Generate API Key​

  1. In Heap, navigate to Account > Manage > Privacy & Security

  2. Scroll down to the API Key section

  3. If you haven't generated an API key yet, click Generate API Key

  4. Copy the API Key that's displayed

    warning

    The API Key is only shown once. Store it securely. If you lose it, you'll need to generate a new one.

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Heap and click Use

  3. Under General Settings:

    • Enter your App ID (e.g., "123456789")
    • Select your Data Center (US or EU)

  4. Under Authentication Type, select API Key

  5. In the Token field, enter your credentials in the format:

    app_id:api_key

    For example:

    123456789:sk_live_abcd1234efgh5678ijkl9012mnop3456
    tip

    Yes, you'll enter the app_id twice - once in General Settings and once in the token. This is required because some endpoints need the app_id in the request body while authentication uses it in Basic auth.

  6. Click Save Changes

4. Test the Connection​

After saving, test one of the tools like "Add User Properties" to verify the connection works correctly.

Key Features and Use Cases​

Event Tracking​

  • Track Custom Event - Send backend events like purchases, subscriptions, or transactions
  • Track Event with User Properties - Combine event tracking with user enrichment in one call
  • Batch Track Events - Import historical events or sync offline data efficiently

User Identity Management​

  • Identify User - Link anonymous visitors to known users (email, user ID)
  • Add User Properties - Enrich user profiles with CRM data, subscription info, behavior attributes
  • Batch Update User Properties - Sync user data from your database or CRM at scale

Account Management (B2B Analytics)​

  • Add Account Properties (Single) - Track company-level attributes for one account
  • Add Account Properties (Bulk) - Update properties for up to 1000 accounts at once
  • Link User to Account - Associate users with their company accounts

GDPR & Data Privacy​

  • Get Auth Token - Obtain temporary token for deletion operations
  • Delete Users - Remove user data across all environments for GDPR compliance
  • Check Deletion Status - Monitor progress of deletion requests

Important Limitations​

Rate Limits​

  • User Properties: 30 requests per 30 seconds per identity per app_id
  • Plan accordingly when updating user properties at scale

Property Constraints​

  • Event names: Maximum 255 characters
  • Property keys: Maximum 512 characters, must be strings
  • Property values: Maximum 1024 characters, must be arrays, booleans, numbers, or strings

Identity Rules​

  • Identify API: Only 1 identity can be mapped to a user_id
  • Identity limits: Maximum 10 different user_ids can be mapped to one identity within a one-month period
  • Subsequent identify calls that exceed these limits are silently ignored

Special Considerations​

  • Email property: Must use lowercase "email" as the key to write to Heap's built-in email property
  • Deletion API: Must use Main Production environment's app_id (other environment IDs will fail)
  • Auth Token: Expires in 5 minutes - obtain a new token before each deletion operation

Troubleshooting​

Wrong Data Center Error​

API requests fail with connection errors or 404 responses.

Cause: You're using the wrong data center endpoint for your Heap account.

Solution:

  1. Check your Heap account settings to determine if you're on US or EU data center
  2. In Webrix, update the Data Center setting under General Settings
  3. US accounts use heapanalytics.com, EU accounts use c.eu.heap-api.com
  4. Save and retry your request

401 Unauthorized Error​

API requests fail with "Unauthorized" or 401 status codes.

Cause: Incorrect API credentials format or invalid app_id/api_key.

Solution:

  1. Verify your token is formatted correctly: app_id:api_key
  2. Check for extra spaces or characters in the token
  3. Ensure your App ID is the numeric environment ID from Heap Projects page
  4. Verify your API Key is the one shown in Privacy & Security settings
  5. For deletion API, ensure you're using the Main Production environment App ID

Rate Limiting (429 Too Many Requests)​

User property updates fail with rate limit errors.

Cause: Exceeding 30 requests per 30 seconds per identity per app_id.

Solution:

  1. Use batch operations when updating multiple users
  2. Implement exponential backoff and retry logic
  3. Space out requests to stay under the rate limit
  4. Consider using the Batch Update User Properties tool for bulk operations

Email Property Not Updating​

The email property doesn't appear or update in Heap user profiles.

Cause: Using an incorrect case for the email property key.

Solution:

  1. Always use lowercase "email" as the property key
  2. Incorrect: "Email", "EMAIL", "eMail"
  3. Correct: "email"
  4. Example: 
    {
      "email": "[email protected]",
      "name": "John Doe"
    }

Deletion API Fails with Unauthorized​

Delete Users or Check Deletion Status fails even with valid credentials.

Cause: Using an environment ID that's not the Main Production environment.

Solution:

  1. The deletion API requires your Main Production environment's App ID
  2. Go to Heap Settings > Projects
  3. Find your "Main Production" environment (or similar)
  4. Use that specific App ID in the token
  5. The deletion API will check and delete across all environments, but authentication must use the main production ID

Identify Call Silently Ignored​

User identification doesn't work or past activity isn't merged.

Cause: Exceeding identity mapping limits (1 identity per user_id, or 10 user_ids per identity per month).

Solution:

  1. Check if the user_id already has an identity mapped to it
  2. Check if the identity already has 10 user_ids mapped in the last month
  3. Heap silently ignores calls that exceed these limits to protect data integrity
  4. Use unique identities for each user to avoid hitting the limits
  5. Don't repeatedly call identify with different user_ids for the same identity

Properties Not Appearing in Heap​

Custom properties don't show up in Heap dashboards or reports.

Cause: Properties may not be defined or labeled in Heap, or there's a delay in processing.

Solution:

  1. After sending properties via API, log into Heap and navigate to Data > Properties
  2. Check if your custom properties appear in the list
  3. It may take a few minutes for new properties to appear
  4. Ensure property values meet the constraints (max 1024 characters, valid types)
  5. Check that the API request succeeded without errors

Connection Timeout or Slow Responses​

API requests are timing out or taking too long.

Cause: Network issues, large batch operations, or Heap service latency.

Solution:

  1. Check Heap's status page for any service disruptions
  2. Reduce batch sizes (e.g., send 100 events at a time instead of 10,000)
  3. Implement retry logic with exponential backoff
  4. For bulk operations, use smaller batches and track progress
  5. Check your network connectivity and firewall rules

Best Practices​

User Identification​

  1. Always identify users before adding user properties - properties can only be added to identified users
  2. Use email as identity when possible for easy cross-referencing with other systems
  3. Call identify early in the user journey (after signup/login) to ensure all activity is tracked

Property Management​

  1. Use consistent naming for properties across your application (e.g., snake_case or camelCase)
  2. Lowercase email key - always use "email" for the built-in email property
  3. Use ISO8601 format for dates and timestamps for proper time-based analysis
  4. Keep values under limits - stay within 255/512/1024 character limits for names/keys/values

Performance​

  1. Batch operations - use batch tools when updating multiple users or tracking multiple events
  2. Respect rate limits - stay under 30 requests per 30 seconds per identity for user properties
  3. Cache auth tokens - when using deletion API, reuse tokens within the 5-minute expiration window
  4. Async processing - run large batch operations asynchronously to avoid blocking your application

Account Analytics (B2B)​

  1. Configure Account ID first - set up account ID in Heap settings before using account APIs
  2. Consistent account_id - use the same account identifier across all tools (CRM ID, domain, etc.)
  3. Link users to accounts - after identifying a user, link them to their account for account-level analysis
  4. Regularly update - periodically sync account properties from your CRM or billing system

Data Privacy​

  1. GDPR compliance - use the deletion API to honor user deletion requests
  2. Main Production app_id - always use the Main Production environment ID for deletion API
  3. Track deletion status - monitor deletion requests to confirm completion
  4. Document retention - keep records of deletion requests for compliance purposes