Skip to main content
TrailsparkDocs

Connecting Heap

Two things you can bring across from Heap

Heap connects to Trailspark in two separate ways, and it is worth knowing which one you want:

What you wantHow to set it up
Segments — who joined and who left a Heap segmentConnect Heap in Settings > Integrations > Heap
Events — what people actually didA Heap Webhook, or Heap Connect on BigQuery

Connecting Heap under Settings does not bring in events, and sending events does not require connecting Heap. Most teams end up doing both.

Connect Heap segments

Connecting Heap lets you pick segments in Heap and have Trailspark follow them. Every few hours, Heap tells Trailspark who has joined each segment and who has left, and those arrive as activity on the people involved.

  1. In Trailspark, go to Settings > Integrations > Heap
  2. On the Connection tab, select Connect with Heap
  3. Sign in to Heap and approve access for Trailspark
  4. In Heap, turn Trailspark on for each segment you want to share
  5. When Heap asks which user property to send, choose email

[!IMPORTANT] Choose email as the identity property in Heap. Trailspark matches people to their company by email address, so a segment sent with an internal user ID cannot be matched as reliably.

Back on the Connection tab you will see the Heap account you connected and when it was connected. Selecting Disconnect stops Trailspark taking segment updates; turn Trailspark off on your segments in Heap as well to stop them being sent.

What arrives

For each person Heap tells us about, you will see an entered segment or left segment activity, with the segment's name. Updates arrive in batches every few hours rather than the moment someone joins, and Heap sends only the changes since the last update.

Info

If the Connection tab says Heap isn't available yet, connecting segments hasn't been switched on for your account. You can still send Heap events today — see the section below.

Send Heap events by webhook

Heap events reach Trailspark the same way any other webhook source does — you configure a Heap Webhook in Heap and point it at your Trailspark webhook URL. Trailspark's API Keys page has a Heap source preset that makes this a copy-paste setup.

Info

Heap Webhooks is a beta feature. If you don't see Webhooks under Heap's Integrations directory, ask Heap support to enable it for your account first.

If your organization instead syncs Heap data to BigQuery via Heap Connect, that is a separate path — see the BigQuery connector documentation for connecting a Heap Connect dataset.

Step 1: Pick the Heap source preset in Trailspark

  1. Go to Settings > API Keys
  2. Create a webhook API key (or use an existing one) and set its Source picker to Heap
  3. Copy the webhook URL shown — it already includes ?source=heap so every event from this key is labeled correctly
  4. Expand Payload template and copy the starter JSON body

Step 2: Configure a webhook in Heap

In Heap:

  1. Go to Integrations > Directory > Webhooks
  2. Create a new webhook for the event you want to send (Heap Webhooks are configured one webhook per labeled event)
  3. Paste the Trailspark webhook URL from Step 1
  4. Build the JSON body using the payload template as a guide, mapping Heap's user, session, and event properties into it
  5. Make sure the body includes at least an email or user ID property so Trailspark can match the event to a person
  6. Save and enable the webhook

Repeat Step 2 for each Heap event you want to send — Heap sends one webhook configuration per event, not one for all events.

Step 3: Verify events are arriving

Back on the API Keys page, expand Recent events on the same key. Trigger the Heap event you configured (or wait for a real one) and it should appear within a few seconds, showing the event name, who it came from, and the properties Heap sent.

Step 4: Map the event to buying-group roles

Use the Create a mapping rule from this event link on the recent event to jump into Signal Mapping with the event pre-filled, or configure it manually — see Signal and Role Attribution.

Next Steps