.png)
Heap Integration Guide
Integrate Heap with enterprise systems through HTTP event and identity APIs, scheduled exports, warehouse workflows, and normalized APIs exposed by Martini.
Heap integration options at a glance
Heap primarily integrates through HTTP APIs for event ingestion, user identification, and supported user-property operations. Martini can receive source-system events, map identities and behavioral properties, and send compliant payloads to Heap. For outbound analytics movement, Martini can orchestrate supported Heap exports or warehouse-oriented integrations into destinations such as Snowflake, BigQuery, or Redshift. Batch behavior, payload limits, export availability, and credentials depend on the applicable Heap API, product configuration, and plan. Heap does not have a confirmed general-purpose GraphQL, SOAP, or universal webhook framework, so scheduled workflows and documented export interfaces are preferred for synchronization.
| Integration point | Supported by Heap? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Heap documents HTTP APIs for event ingestion, user identification, user-property operations, and selected administrative or export use cases. Endpoint availability and credentials can depend on the account plan and product configuration. | Martini can consume Heap HTTP APIs and send authenticated requests from workflows. It can also expose REST APIs that abstract Heap payloads for internal consumers. |
| Authentication | Yes | Event ingestion commonly uses an App ID, while selected server-side or administrative APIs use API credentials or keys. User identity fields associate events with Heap users. | Martini stores App IDs, API keys, tokens, and destination credentials in secrets or secure environment configuration and injects them into workflow calls without embedding them in mappings. |
| Bulk / async / batch APIs | Limited | Heap supports server-side event ingestion, and some ingestion or export workflows may support batching. Payload limits, batch behavior, and account eligibility must be confirmed for the applicable API and plan. | Martini can batch where the documented Heap interface permits it, preserve failed records, track submitted batches, and replay only controlled failures. |
| Database / analytics access | Limited | Heap supports export and warehouse-oriented analytics use cases, but this is not direct transactional database access to Heap's internal systems. | Martini can coordinate documented exports, retrieve or transform delivered data, and load an authorized warehouse or query the destination warehouse rather than assuming direct Heap database connectivity. |
| Webhooks / outbound callbacks | Not confirmed | No general-purpose Heap webhook or callback framework covering every event, user change, session, or page view was confirmed. | Martini can receive webhooks from other systems, but Heap outbound callbacks should be used only when a specific product, integration, and account configuration documents them. |
| GraphQL APIs | Not confirmed | No official general-purpose Heap GraphQL API was confirmed for integration use. | Martini should use Heap's documented HTTP APIs or supported export mechanisms instead of assuming GraphQL access. |
| SOAP APIs | No | No official Heap SOAP API was identified in the supplied research. | Martini should not design a Heap integration around SOAP. It can still consume Heap HTTP APIs and orchestrate supported exports. |
| File / attachment APIs | No | Heap is not documented as providing a general-purpose file or attachment API for business documents. | Martini can orchestrate references or metadata through a separate storage or file-transfer system, but it should not treat Heap as the document store. |
How Heap exposes data and business events
Heap REST APIs
Heap's primary integration surface is its HTTP API model. The Track API supports sending events with user identity, event names, timestamps, and event properties, while the Identify API supports associating users and supported user attributes. Other HTTP or administrative operations may vary by plan and configuration.
Martini implementation pattern
Martini implementation pattern: a workflow receives an application event or retrieves source data, applies identity and event-schema rules, stores credentials in Martini secrets, and calls the appropriate Heap HTTP endpoint. The workflow records response status, correlation data, and replay eligibility while keeping transport retries separate from business-level replay.
Implementation sequence
Heap batch ingestion
Heap supports server-side event ingestion, and some use cases may allow batching or asynchronous processing. Exact batch limits, payload behavior, and account eligibility must be verified against the applicable Heap API and plan rather than assumed.
Martini implementation pattern
Martini implementation pattern: a scheduled or queue-driven workflow groups eligible events only where the documented Heap interface permits it, submits a controlled batch, records the source event identifiers, and isolates rejected items for review or replay. The workflow does not assume that HTTP retries are idempotent.
Implementation sequence
Heap exports and warehouse integrations
Heap supports export and warehouse-oriented analytics use cases, including data movement to destinations such as Snowflake, BigQuery, or Amazon Redshift when the relevant product and account configuration are enabled. This is distinct from direct access to Heap's internal database.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow initiates or retrieves a documented export, tracks its state, transforms users, events, sessions, pages, and properties into the destination model, and loads the result while recording export windows and checkpoints. Martini can also expose a normalized API over the warehouse or processed data.
Implementation sequence
Heap identity APIs
Heap provides identity-oriented HTTP operations for associating events with users and updating supported user properties. Identity design should be established before production because inconsistent identifiers can fragment user histories.
Martini implementation pattern
Martini implementation pattern: a workflow receives user or account changes, selects the canonical identifier, separates identity establishment from property updates and event submission, filters sensitive data, and calls the relevant Heap API. Corrections, deletion requests, and privacy handling are represented as explicit business cases rather than inferred from retries.
Implementation sequence
Common Heap integration patterns
Pattern 1: Send product usage events to Heap
When to use this pattern
Use this pattern when Salesforce, a backend service, or another operational application produces customer, subscription, or product lifecycle events that should be analyzed in Heap. It is appropriate for feature adoption, account health, and conversion signals.
Integration direction
Example Mapping
| Heap Field | Canonical Field | Target Field |
|---|---|---|
| Account.Id | accountId | user or account property |
| Contact.Id | userId | Heap identity |
| Opportunity.StageName | opportunityStage | event or user property |
| Subscription.Status | subscriptionStatus | event property |
Martini implementation pattern
Martini receives or retrieves the source change, resolves the Heap identity, maps the event taxonomy and properties, validates types and privacy rules, and sends the HTTP event payload. The workflow stores source event identifiers, separates transient HTTP retries from replay, and prevents duplicate submissions through deterministic correlation keys where possible.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- secrets management
- error handling
Pattern 2: Synchronize user identities and properties
When to use this pattern
Use this pattern when a system such as Segment, Salesforce, or HubSpot is the source of customer identity, account, plan, or lifecycle attributes and Heap needs consistent segmentation data. The design should distinguish identity establishment, property updates, behavioral events, and privacy corrections.
Integration direction
Example Mapping
| Heap Field | Canonical Field | Target Field |
|---|---|---|
| contact.id | externalUserId | Heap user identity |
| company.id | accountId | account user property |
| lifecycle_stage | lifecycleStage | user property |
| subscription_plan | plan | user property |
Martini implementation pattern
A Martini workflow consumes source changes or scheduled extracts, applies canonical identity and consent rules, maps supported user properties, and invokes Heap identity operations. Validation rejects incomplete identities, while correction and deletion cases follow explicit privacy rules and are auditable.
Martini capabilities used
- workflows
- API consumption
- data mapping
- validation
- business rules
- secure configuration
Pattern 3: Export Heap analytics to a warehouse
When to use this pattern
Use this pattern when product analytics must be combined with operational, marketing, or customer data in Snowflake, BigQuery, or Amazon Redshift. Availability depends on the Heap export product, destination configuration, and account plan.
Integration direction
Example Mapping
| Heap Field | Canonical Field | Target Field |
|---|---|---|
| event.id or source identifier | sourceEventId | event_id |
| event.timestamp | occurredAt | occurred_at |
| user.id | userId | user_id |
| event.properties | properties | properties_json |
Martini implementation pattern
A scheduled Martini workflow coordinates the supported export, tracks completion, transforms the delivered model, and loads warehouse tables incrementally. It uses export timestamps or other documented cursors, overlap windows for late data where needed, checkpoint persistence, and duplicate suppression before committing a load.
Martini capabilities used
- scheduled workflows
- workflow orchestration
- data mapping
- JSON handling
- database connectivity
- error handling
Pattern 4: Expose a normalized Heap analytics API
When to use this pattern
Use this pattern when internal applications need user activity or product engagement data without receiving Heap credentials or coupling directly to Heap-specific payloads. The source may be a supported Heap API, an authorized warehouse export, or processed integration data.
Integration direction
Example Mapping
| Heap Field | Canonical Field | Target Field |
|---|---|---|
| heap_user_id | userId | customer_id |
| event_name | activityType | activity_type |
| event_timestamp | occurredAt | occurred_at |
| event_properties | attributes | attributes |
Martini implementation pattern
Martini exposes a secured REST API, validates and authorizes the request, calls Heap or an intermediate warehouse, and maps the response into an enterprise schema. The workflow applies filtering, pagination, error responses, and logging so consumers do not depend on Heap-specific credentials or response formats.
Martini capabilities used
- API exposure
- API consumption
- authorization
- data mapping
- business rules
- error handling
Applications commonly integrated with Heap
Heap can be integrated with operational, marketing, analytics, and support applications to connect behavioral data with customer, lifecycle, and warehouse context. The following are practical enterprise integration targets; packaged vendor integrations should be validated separately where noted.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Associate product usage with Accounts, Contacts, Leads, and Opportunities to support customer health, adoption, and sales context. | Salesforce → Martini → Heap | A Martini workflow consumes Salesforce changes or scheduled extracts, maps Salesforce identifiers and lifecycle fields to Heap identities, user properties, and events, then sends validated HTTP requests to Heap. A separate workflow can publish selected Heap-derived engagement signals back to Salesforce through its APIs. |
| HubSpot | Combine marketing lifecycle data with product engagement for segmentation, campaign decisions, and customer journey analysis. | HubSpot → Martini → Heap | Martini retrieves HubSpot contact and lifecycle data, applies identity and consent rules, transforms properties into Heap-compatible payloads, and submits identify or event requests. Exported Heap segments can be transformed for a controlled reverse synchronization where supported. |
| Segment | Forward standardized customer and event data into Heap while maintaining consistent identity conventions across analytics tools. | Segment → Martini → Heap | Martini receives or retrieves Segment-shaped events, validates event names and property types, applies deterministic identity mapping, and calls Heap event-ingestion or identify APIs. Failed submissions are retained for controlled replay without assuming automatic idempotency. |
| Snowflake | Centralize Heap events and user data with operational and customer data for reporting, modeling, and reverse workflows. | Heap → Martini → Snowflake | A scheduled Martini workflow coordinates a supported Heap export or reads data made available through a warehouse integration, tracks export state, transforms schemas, and loads data into Snowflake while storing checkpoints and duplicate-suppression keys. |
| Google BigQuery | Analyze Heap events alongside application, advertising, and customer datasets in a cloud warehouse. | Heap → Martini → Google BigQuery | Martini orchestrates the applicable Heap export process, retrieves or receives the resulting data, normalizes timestamps and properties, and writes batches to BigQuery with export-window tracking and retry handling. Availability depends on Heap configuration and plan. |
| Amazon Redshift | Consolidate product analytics with enterprise reporting and customer analytics in an existing warehouse environment. | Heap → Martini → Amazon Redshift | Martini schedules export coordination, transforms Heap users, events, sessions, and properties into warehouse tables, loads Redshift incrementally, and records source windows and load status to prevent duplicate processing. |
| Jira | Relate product usage and feature adoption to releases, issues, and delivery information. | Jira → Martini → Heap | Martini retrieves selected Jira release or issue metadata, maps stable identifiers into Heap event or user properties, and submits the resulting payloads through Heap's HTTP APIs. This is an architectural integration pattern rather than a confirmed packaged Heap integration. |
| Zendesk | Combine support activity with product usage to identify adoption, churn, and support-risk signals. | Zendesk → Martini → Heap | Martini consumes selected Zendesk customer or case attributes, applies privacy and identity rules, and sends relevant user properties or support-related events to Heap. A reverse flow can publish approved Heap-derived context to Zendesk where the target API and governance allow it. |
How to build a Heap integration in Martini
Objective
Establish the Heap API or export connection and keep credentials outside workflow definitions.
Instructions in Martini
- Confirm the applicable Heap API, export product, plan, and credential model.
- Store App IDs, API keys, tokens, and destination credentials in Martini secrets.
- Configure environment-specific endpoints and access restrictions.
Objective
Select a trigger that matches Heap's receive-oriented integration model and the synchronization requirement.
Instructions in Martini
- Use an inbound API or source event when operational systems produce data for Heap.
- Use a scheduler for exports, warehouse synchronization, and reconciliation.
- Do not assume Heap provides a universal outbound webhook stream.
Objective
Receive source events or obtain Heap data through documented APIs and supported exports.
Instructions in Martini
- Call the Track or Identify API as appropriate for inbound Heap ingestion.
- For outbound analytics, initiate or retrieve the supported export and track its state.
- Implement documented pagination, cursors, export windows, and checkpoints.
Objective
Convert source objects and exported analytics into governed enterprise schemas.
Instructions in Martini
- Map canonical identities to Heap user identities.
- Transform event names, user properties, and event properties without embedding changing values in event names.
- Normalize timestamps, data types, and JSON structures.
Objective
Enforce validation, privacy, identity, and duplicate-handling rules before data is committed.
Instructions in Martini
- Validate required identities, event names, property types, and payload sizes.
- Apply consent, minimization, masking, retention, and deletion rules.
- Use deterministic correlation keys and source identifiers to control duplicate delivery.
Objective
Submit valid payloads to Heap or load processed Heap data into an authorized destination.
Instructions in Martini
- Send authenticated event or identity requests to Heap.
- Load supported export data into Snowflake, BigQuery, Amazon Redshift, or another approved destination.
- Expose a secured Martini API when internal consumers need a normalized analytics view.
Common Heap data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Users | Identified people or anonymous visitors associated with Heap activity and identity resolution. | Salesforce, HubSpot, Segment, Snowflake, BigQuery | Martini maps canonical user identifiers, applies privacy rules, and invokes Heap identify or user-property APIs. It can also transform exported users for warehouse loading. |
| Events | Custom or automatically captured user actions, including product, lifecycle, and feature interactions. | Heap, Snowflake, BigQuery, Amazon Redshift | Martini validates event names and property types, adds timestamps and correlation identifiers where supported, submits HTTP event payloads, and tracks replay state. |
| Sessions | Groups of user activity occurring during a visit or interaction period for behavioral analysis. | Snowflake, BigQuery, Amazon Redshift, reporting platforms | Martini handles sessions primarily through supported exports or warehouse data, normalizing timestamps and maintaining incremental extraction checkpoints. |
| Pages | Page views and page-related activity captured from websites or applications. | Snowflake, BigQuery, Amazon Redshift, internal analytics services | Martini can transform exported page activity into enterprise schemas or expose a normalized API without assuming direct transactional access to Heap. |
| User properties | Attributes associated with a user, such as account identifiers, plan information, consent state, or customer segments. | Heap, Salesforce, HubSpot, Segment, customer data platforms | Martini applies field mapping, data-type validation, privacy filtering, and update rules before calling Heap user-property operations or synchronizing approved attributes. |
| Event properties | Attributes attached to an event, such as product identifiers, page metadata, transaction values, or feature names. | Heap, Snowflake, BigQuery, Amazon Redshift | Martini maps source fields into governed event properties, validates required types, removes unnecessary sensitive data, and preserves source identifiers for duplicate control. |
Authentication and security considerations
Authentication and identity
Heap authentication varies by integration surface. Event ingestion commonly uses an App ID, while selected server-side or administrative APIs use API credentials or keys. Heap user identities must be designed explicitly so source identifiers remain stable and do not fragment user histories.
Secrets and access control
Store App IDs, API keys, tokens, and warehouse credentials in Martini secrets or secure environment configuration. Limit access to the Heap project, environment, export, or administrative operation required by each workflow.
Privacy
- Apply consent, data minimization, masking, and retention rules before sending user or event properties.
- Handle deletion and correction requests as explicit business workflows.
- Prevent sensitive values from appearing in workflow logs, payload diagnostics, or exported analytics data.
Operational considerations for Heap integrations
Rate and payload limits
Confirm Heap request rates, events per request, payload sizes, concurrency, export volumes, and event quotas for the applicable plan. Use batching only where the documented interface supports it.
Incremental processing
Implement documented pagination or export cursors, persist checkpoints after successful processing, and use overlapping extraction windows when late-arriving data is possible. Suppress duplicates created by overlap.
Reliability and schema control
- Retry transient failures with controlled backoff and preserve rejected records for replay.
- Monitor authentication failures, validation errors, rate-limit responses, export completion, and warehouse load status.
- Validate event names, property types, timestamp formats, and unexpected schema or cardinality changes.
- Use explicit timestamps and account for clock differences, delayed events, and ordering variation.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate beyond a single API call
Scripts can send a Heap event, but enterprise integrations also require identity resolution, privacy rules, validation, checkpointing, warehouse loading, retries, and operational monitoring. Martini coordinates these concerns in maintainable workflows.
Separate systems without tight coupling
Martini can consume source APIs, call Heap's HTTP interfaces, coordinate supported exports, and expose normalized APIs without forcing every application to understand Heap-specific payloads or credentials.
Reuse and govern integration logic
- Centralize mappings for users, events, user properties, and event properties.
- Apply environment-specific secrets and business rules consistently.
- Handle errors, replay, scheduling, and observability as part of the integration design.
Frequently asked questions
Heap can be integrated through its documented HTTP APIs for event ingestion, user identification, and supported user-property operations. Enterprise workflows can also coordinate supported exports or warehouse integrations for analytics data movement. Heap does not have a confirmed universal webhook, GraphQL, or SOAP integration model.
Yes. Martini can consume Heap's documented HTTP APIs, send event and identity payloads, orchestrate supported export or warehouse workflows, and expose APIs that normalize Heap data for other applications. No native Martini Heap connector is documented in the supplied materials.
No. A dedicated Heap connector is not required. Martini can integrate using Heap's confirmed HTTP APIs, App IDs or API credentials, supported export interfaces, warehouse workflows, and standard enterprise orchestration patterns.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Heap with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Heap, cloud infrastructure, warehouses, or other third-party systems based on their subscription, usage, and deployment models.
Use Heap's HTTP Track and Identify APIs for sending events, associating users, and updating supported user properties. Use documented export or warehouse-oriented interfaces for outbound analytics synchronization. GraphQL and SOAP were not confirmed, and webhook coverage should not be assumed.
A general-purpose Heap webhook or outbound callback framework was not confirmed. Heap is primarily designed to receive behavioral data, so outbound synchronization should use supported exports, warehouse integrations, or documented APIs. Any product-specific callback must be validated separately.
Martini workflows can use scheduled extraction, export checkpoints, pagination, overlap windows, and incremental processing. Mapping converts source identities and attributes into Heap users, events, user properties, and event properties. Source identifiers, deterministic correlation keys, validation, and controlled retries help manage duplicates, but HTTP retries should not be assumed to be automatically idempotent.
Yes. Martini can expose a secured REST API that calls Heap or an authorized warehouse, applies authentication, validation, filtering, and transformation, and returns a normalized enterprise schema. This prevents internal consumers from depending directly on Heap credentials or vendor-specific payload formats.
Related Martini documentation
Workflows
Data
Connect Heap with Martini
Use Martini to integrate Heap's event and identity APIs, coordinate supported analytics exports, and expose governed data services for enterprise applications.