Creating a new Heap Integration

You can use the Segments Sync API to build private integrations that are only enabled for your own internal use to send segment data to your internal systems. These do not need to be published to be used within your own account.


This API is primarily for Heap partners, though we have also made it available for customers to use to build their own private integrations. This integration will not be published anywhere publicly.

To set these up, complete the steps below.

  1. Request access to the Developers Hub and a Heap test account from your Customer Success Manager.

  2. In your Heap test account, navigate to the Integrations > Developer Hub and click Create new integration. Give it a memorable name!

  3. Set up a webhook endpoint (spec, example) to receive segmentation data from Heap. Heap will call this endpoint every 4 hours with information about which users have entered or exited the segment since the last call.

  4. Go back to the Developer Hub to complete the integration draft. Input the webhook URL (from step 3). You can fill in any value for the OAuth Redirect URL and identity matching information (these are only important if you plan to publicly list the integration).

  5. You can test the integration by navigating to Definitions > Segments in your Heap account. Select or create a test segment and scroll down until you see the Integrations card in the segment details. You should see your integration listed here by its name.

  6. Toggle this ON to sync the test segment to your integration. It should prompt you to select an identity matching key to identify users between Heap and your integration. Whatever you select here will be the user property values that Heap sends to your webhook for each user in the Segment.

For questions, reach out to your Customer Success Manager or to [email protected].