Overview

Marketo is marketing automation software that provides inbound marketing, social marketing, CRM, and other related services. The Heap Marketo integration is bi-directional:

• Automatically capture interesting moments from Marketo as events in Heap (open email, send email, etc)
• Send behavioral data into Marketo as static lists to run email campaigns or change lead scores

With Heap’s Marketo source, you’ll be able to answer:

• How do users that open your recent feature blast go on to interact with your product?
• How many email touches does it take to properly nurture a lead to signup?
• How do your email campaigns influence customer engagement and retention?

Source

Setup

This guide provides setup instructions for the Marketo integration with Heap, including information on the payout and PII-free payload.

Step 1: Enable the Marketo Source in Heap

The instructions in this step only apply if you send email addresses as a user property or identity in Heap. If you are not sending email addresses in Heap, contact support@heap.io to complete step 1.

Prior to completing the instructions below, you need to reach out to your Customer Success Manager to enable this integration.

Once your CSM has set it up, navigate to Integrate > Sources > Marketo and click the Connect button. You’ll be prompted to confirm your connection and select an email user property.

Heap will confirm that the source is connected. Now you’ll need to go to Marketo to complete setup.

Step 2: Configuring the Marketo → Heap Webhook

Create Webhook in Marketo

In your Marketo account, create a Heap Webhook as follows:

• Navigate to Admin, then select Integration > Webhooks > New Webhook
• Provide a Webhook Name, such as Heap Analytics
• Set the URL as https://heapanalytics.com/api/integrations/marketo
• Set the Request Type as POST

Add Payload or PII-Free Payload Template

Next, you’ll set the Template based on whether this is a Payload or PII-Free Payload. We recommend using the PII-Free Payload if you are not sending email addresses as your Email User Property.

See our Payload or PII-Free Payload instructions to decide which ones to use.

You will need to change the app ID to your own application ID, which you can find in Heap under Account > Manage > Projects. We recommend testing this in your development environment first, then confirming the setup within Heap.

You’re welcome to modify the tokens used in the request, though our default format sends over all non-custom tokens used by Marketo.

Option 1: Payload

This is the payload you will copy during setup. It assumes an email property or identity exists in Heap on which to join Marketo data.

To include custom properties from your Marketo instance, simply add them to the payload below.

For user properties, the key should be lead_ or company_ (as applicable), followed by the REST API name of the property, and the value should be the token variable for that field. Learn more about Marketo tokens via Marketo’s documentation.

For event properties, the key should be trigger_ followed by the REST API name of the property, and the value should be the token variable for that field. Learn more about Marketo tokens in Marketo’s documentation.

{
  "app_id": "123456789",
  "identity": {{Lead.Email Address}},
  "properties": {
    "trigger_trigger_name": {{trigger.Trigger Name}},
    "lead_anonymousIP": {{Lead.Anonymous IP}},
    "lead_blackListed": {{Lead.Black Listed}},
    "lead_city": {{Lead.City}},
    "lead_country": {{Lead.Country}},
    "lead_createdAt": {{Lead.Created At}},
    "lead_dateOfBirth": {{Lead.Date of Birth}},
    "lead_doNotCall": {{Lead.Do Not Call}},
    "lead_doNotCallReason": {{Lead.Do Not Call Reason}},
    "lead_email": {{Lead.Email Address}},
    "lead_emailInvalid": {{Lead.Email Invalid}},
    "lead_emailInvalidCause": {{Lead.Email Invalid Cause}},
    "lead_fax": {{Lead.Fax Number}},
    "lead_firstName": {{Lead.First Name}},
    "lead_fullName": {{Lead.Full Name}},
    "lead_inferredCity": {{Lead.Inferred City}},
    "lead_InferredCompany": {{Lead.Inferred Company}},
    "lead_inferredCompany": {{Lead.Inferred Country}},
    "lead_inferredMetropolitanArea": {{Lead.Inferred Metropolitan Area}},
    "lead_inferredPhoneAreaCode": {{Lead.Inferred Phone Area Code}},
    "lead_inferredPostalCode": {{Lead.Inferred Postal Code}},
    "lead_inferredStateRegion": {{Lead.Inferred State Region}},
    "lead_mktoIsCustomer": {{Lead.Is Customer}},
    "lead_isEmployee": {{Lead.Is Employee}},
    "lead_mktoIsPartner": {{Lead.Is Partner}},
    "lead_title": {{Lead.Job Title}},
    "lead_lastName": {{Lead.Last Name}},
    "lead_leadSource": {{Lead.Lead Source}},
    "lead_marketingSuspended": {{Lead.Marketing Suspended}},
    "lead_middleName": {{Lead.Middle Name}},
    "lead_mobilePhone": {{Lead.Mobile Phone Number}},
    "lead_originalReferrer": {{Lead.Original Referrer}},
    "lead_originalSearchEngine": {{Lead.Original Search Engine}},
    "lead_originalSearchPhrase": {{Lead.Original Search Phrase}},
    "lead_originalSourceInfo": {{Lead.Original Source Info}},
    "lead_originalSourceType": {{Lead.Original Source Type}},
    "lead_mktoPersonNotes": {{Lead.Person Notes}},
    "lead_phone": {{Lead.Phone Number}},
    "lead_registrationSourceInfo": {{Lead.Registration Source Info}},
    "lead_registrationSourceType": {{Lead.Registration Source Type}},
    "lead_salutation": {{Lead.Salutation}},
    "lead_unsubscribed": {{Lead.Unsubscribed}},
    "lead_unsubscribedReason": {{Lead.Unsubscribed Reason}},
    "lead_updatedAt": {{Lead.Updated At}},
    "company_account_owner_email_address": {{Company.Account Owner Email Address}},
    "company_address": {{Company.Address}},
    "company_annual_revenue": {{Company.Annual Revenue}},
    "company_city": {{Company.City}},
    "company_company_name": {{Company.Company Name}},
    "company_company_notes": {{Company.Company Notes}},
    "company_country": {{Company.Country}},
    "company_industry": {{Company.Industry}},
    "company_main_phone": {{Company.Main Phone}},
    "company_num_employees": {{Company.Num Employees}},
    "campaign_name": {{campaign.name}},
    "campaign_id": {{campaign.id}},
    "campaign_description": {{campaign.description}},
    "trigger_name": {{trigger.Name}},
    "trigger_link": {{trigger.Link}},
    "trigger_subject": {{trigger.Subject}},
    "trigger_category": {{trigger.Category}},
    "trigger_details": {{trigger.Details}},
    "trigger_web_page": {{trigger.Web Page}},
    "trigger_sent_by": {{trigger.Sent By}},
    "trigger_referrer": {{trigger.Referrer}},
    "trigger_search_engine": {{trigger.Search Engine}},
    "trigger_search_query": {{trigger.Search Query}}
    }
}

Option 2: PII-Free Payload

If you cannot send PII to Heap, you may edit the payload above. Below is an example of a PII-free payload.

The custom identifier mapped to identity must match a user property or identity in your Heap account. The format is {{ Object.Field Name }}.

To include custom properties from your Marketo instance, simply add them to the payload below.

For user properties, the key should be lead_ or company_ (as applicable), followed by the REST API name of the property, and the value should be the token variable for that field. Learn more about Marketo tokens via Marketo’s Tokens Overview doc.

For event properties, the key should be trigger_ followed by the REST API name of the property, and the value should be the token variable for that field. Learn more about Marketo tokens should be the token variable for that field. Learn more about Marketo tokens via Marketo’s Tokens Overview doc.

{
  "app_id": "123456789",
  "identity": {{Object.Field Name}},
  "properties": {
    "campaign_name": {{campaign.name}},
    "campaign_id": {{campaign.id}},
    "campaign_description": {{campaign.description}},
    "trigger_trigger_name": {{trigger.Trigger Name}},
    "trigger_name": {{trigger.Name}},
    "trigger_link": {{trigger.Link}},
    "trigger_subject": {{trigger.Subject}},
    "trigger_category": {{trigger.Category}},
    "trigger_details": {{trigger.Details}},
    "trigger_web_page": {{trigger.Web Page}},
    "trigger_sent_by": {{trigger.Sent By}},
    "trigger_referrer": {{trigger.Referrer}},
    "trigger_search_engine": {{trigger.Search Engine}},    
    "trigger_search_query": {{trigger.Search Query}}
    }
}

Set Request Token & Response Type

Specify the Request Token Encoding as JSON and the Response Type as None.

Click Create to finish creating your webhook. In the finished view, click Webhook Actions > Set Custom Header and apply the header Content-type with the value of application/json.

Click Save.

Step 3: Create a New Smart Campaign

Visit Marketing Activities and select New > New Smart Campaign. We suggest putting it in the default Data Management folder and giving it a name like Heap.

Add Triggers for the Smart Campaign

Next, select Smart List and define the triggers desired. You can determine which triggers you’d like to send events to Heap based off of and the filters that you’d like to base them on, but we recommend sending as much data as possible. In particular, you’ll want to send the following most likely:

  * `Clicks Link in Email` 
    - `Email is any` 
  * `Unsubscribes from Email` 
    - `Email is any` 
  * `Sent Forward to Friend Email` 
    - `Email is any` 
  * `Opens Email` 
    - `Email is any` 
  * `Email is Delivered` 
    - `Email is any` 
  * `Email Bounces Soft` 
   - `Email is any` 
  * `Email Bounces` 
    - `Email is any` 
  * `Open Sales Email` 
    - `Subject is any` 
  * `Is Sent Sales Email` 
    - `Subject is any` 
  * `Lead is created` 

Review the Qualification Rules

As a best practice, we recommend reviewing the Smart Campaign Qualification Rules after creating your Smart Campaign. Sometimes, the default setting will be that a user may trigger the Smart Campaign (and thus the webhook to Heap) “only once”. This should be changed to “every time” so that Heap ingests a Marketo event every time that a user triggers the Smart Campaign. Simple instructions to do this can be found in Marketo’s documentation on Qualification Rules.

Link Webhook to the Flow

From the same page, select Flow and drag Integration > Call Webhook from the right-hand column and specify it as the first step in the flow. Specify the Webhook as the Heap webhook.

Once the above has been completed, visit Schedule and select Activate to activate this campaign.

Once the integration is enabled, test the data feed into Heap via Live View. Assuming everything has been configured properly, you’ll start seeing custom events populated in Heap with events titled based on the Trigger Name in Marketo.

Data Format

Once enabled, Heap will automatically ingest all Marketo interesting moments as events within the Marketo source. The event types in Heap map to the trigger name in Marketo.

User Properties

Once enabled, Heap will automatically captures all user properties according to the payload set above. We also support custom fields. If you have custom fields with important data, please reach out to support@heap.io with details.

Destination (Marketo Data Connector)

This integration allows you to send Heap segments into Marketo as a static list, updated every 4 hours.

Step 1: Create an API Only user and Assign API Role in Marketo (Marketo Admin Step)

You’ll need the user to create a LaunchPoint in step 2. The role assigned should have the Access API permissions:

Step 2: Create a LaunchPoint and Get Credentials from Marketo (Marketo Admin Step)

Log into Marketo and navigate to Admin > Integration > Web Services.

Create a new service and set the API Only user from step 1:

After you save the service, click “view details” and copy the client ID and client secret for the next step:

You’ll also need the Rest URL for the next step, which you can get under Admin > Integration > Web Services > Rest API Endpoint.

Step 3: Configure Access in Heap

In Heap, navigate to Integrate > Sources > Marketo. In the Data Out section, you will see either an option to Set Up or Contact Us. If you see Contact Us, reach out to your Customer Success Manager to enable this feature for your account.

Step 4: Set Join Key for Data Connector

You’ll need to input the Client ID, Client Secret, and REST URL generated from Marketo. Once copied over, click Confirm.

You’ll be prompted to select the Heap User ID and Marketo User ID to map users between the two platforms. This is typically the user’s email address, though you can use any IDs that match.

Once you click Confirm, the Data Out section will show as connected on the Marketo page.

Step 5: Send Segment to Marketo

Navigate to Definitions > Segments in Heap and select the segment you want to send to Marketo. In the segment details view, you’ll see a toggle to enable this segment. We only allow you to have 30 segments recurrently syncing to Marketo at one time. This segment will sync every 4 hours after it’s enabled.

Step 6: View Synced Heap Segments and Use in Campaigns

You’re now set up to use Heap segments in Marketo lists! Note that the Marketo lists have the exact same name as the segment that is set up in Heap, and that it will be made available as a system list in Marketo.