Availability : Customers part of our Early Adopter Program for this feature.
Real time Engagement Scoring triggers a fresh behavioral score the moment a meaningful event activity occurs. The score reflects the lead’s cumulative weighted engagement over the past 90 days, not just the single event that triggered the calculation and writes directly back to the matching Salesforce Lead record within minutes. Sales reps see an up-to-date engagement score in Salesforce without any manual action.
This Scoring targets a end-to-end latency of 10 minutes - meaning scoring requests complete from trigger receipt to Salesforce Lead writeback within 10 minutes under normal operating conditions.
The Solution
How it works - High Level Flow
What Gets Written to Salesforce
Once scored, the fields are updated on the Lead record matching the provided email. The Salesforce fields updated can be found in Integrations → Push configuration.
For example, the typical fields in your Salesforce Sync will be:
Salesforce Field | Description |
|---|---|
Likelihood to Buy Score (0-100) | Behavioural score (0-100) reflecting 90-day cumulative engagement |
Likelihood to Buy Segment | Segment label (e.g. very high, high, medium, low) |
Likelihood to buy Signals | Driving signals that contributed to the score |
No Heavy Lifting on Your End: Your only integration touchpoint is configuring a trigger - either a Marketo or a Salesforce Trigger. HG Insights handles all data fetching, scoring logic, and Salesforce writeback.
Works Like Batch Scoring
The HG Insights fields mapped in your existing batch sync are used for fast lane scoring automatically. No changes to your existing field Mapping are needed.
Rate Limits
How it works - High Level Flow
Step 1: Generate an API Key
Login to admin.hginsights.com as an Administrator
Navigate to Settings→ API Key
Select Create API Key, Keys follow the format
hg_v2_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Store the key securely - it is used in Authorization header for every scoring request
Step 2: Verify Salesforce Lead field names
Log in to admin.hginsights.com and navigate to Integrations > Salesforce.
Click Push Settings and select the Salesforce Lead Fields tab.
Confirm the three Engagement fields are mapped to your desired Salesforce Lead fields:
Action Required: If these fields do not exist on the Lead object in your Salesforce org, your Salesforce administrator will need to create them as custom fields before testing the writeback.
Step 3: Setup your Trigger
Marketo Trigger
Setting up Marketo Webhook Trigger - Using Webhooks + Smart Campaigns
Create Webhook
Navigate to Admin → Webhooks → New Webhook and fill in the fields as shown below.
Add the Authorization header — click Edit Request Headers inside the webhook
Create a Smart Campaign: Marketing Activities —> New Smart Campaign
Create a new Smart Campaign (e.g. "HG - Real-Time Score Trigger") and open the Smart List tab. Add a trigger that corresponds to the qualifying product action. The most common triggers are shown below.
3. Add a Flow Step: Flow tab —> Call Webhook
Once the flow is configured, click Activate Campaign. The campaign is now live.
Marketo treats any 2xx response as success. The HG Insights API returns HTTP 202 Accepted immediately, the actual scoring happens asynchronously in the background. Marketo will log the call as successful. The Salesforce Lead record is updated with the new real-time engagement score.
Salesforce Trigger - 2 Options
Option 1 : Salesforce Flow + HTTP Callout
Step 1 — External Credential
Where: Setup → Security → Named Credentials → External Credentials tab
Who: Salesforce Administrator | Do once — required for all users of the integration
The External Credential stores your HG Insights API key encrypted at the Salesforce platform level. It is never visible in code, Flow definitions, or admin views after saving.
1.1 Create the External Credential
Go to Setup → Security → Named Credentials.
Click the External Credentials tab.
Click New and fill in the fields below.
Click Save. You land on the External Credential detail page.
1.2 Add the API Key as a Named Principal
On the External Credential detail page, scroll down to Principals and click New.
Under Authentication Parameters click Add, then set:
Name: Authorization
Value: Bearer hg_v2_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (your full key with 'Bearer ' and a space before it)
Click Save. The token is now encrypted. It cannot be retrieved after saving.
Step 2 — Named Credential and Custom Header
Where: Setup → Security → Named Credentials
Who: Salesforce Administrator | Do once
2.1 Create the Named Credential
The Named Credential defines the API base URL and references the External Credential. Apex and Flow reference it by the name HG_Insights_API.
Still on the Named Credentials page, click the Named Credentials tab.
Click New
Complete the fields as shown and click Save.
URL field is the base domain only — no path
Correct: https://api.hginsights.com
Wrong: https://api.hginsights.com/data-api/v2/scoring/behavioral/live
Wrong: https://https://api.hginsights.com (double https causes 500 Squid proxy error)
The path /data-api/v2/scoring/behavioral/live goes in the Flow HTTP Callout action, not here
2.2 Add the Authorization Custom Header
With Custom authentication protocol, Salesforce does not automatically send the Authorization header unless you explicitly add it as a Custom Header. This is a required step that is easy to miss — without it the API returns 401 Unauthorized.
Go to Setup → Named Credentials. Click HG Insights API.
Scroll down to Custom Headers and click New.
Fill in the fields as shown and click Save.
Step 3 — Remote Site Setting
Where: Setup → Security → Remote Site Settings
Who: Salesforce Administrator | Do once
Salesforce blocks all outbound HTTP calls to unlisted domains even when using a Named Credential. The HG Insights API domain must be explicitly added here.
Go to Setup → Security → Remote Site Settings and click New Remote Site.
Complete the fields as shown and click Save.
Step 4 — Permission Set for Credential Access
Where: Setup → Users → Permission Sets
Who: Salesforce Administrator
Salesforce requires explicit permission set access to use an External Credential — even for System Administrators. Without this step the Flow fails with: 'We couldn't access the credential(s).'
4.1 Create a new Permission Set
Go to Setup → Users → Permission Sets.
Click New at the top of the list. (Do not click 'Create New View' — that is a different action.)
Fill in:
Label: HG Insights API Access
API Name: HG_Insights_API_Access (auto-fills)
License: --None--
Click Save. You land on the Permission Set detail page.
4.2 Enable External Credential Principal Access
On the Permission Set detail page, scroll down and click External Credential Principal Access.
Click Edit.
Move HG_Insights_API - BearerToken from Available to Enabled.
Click Save.
4.3 Assign the Permission Set to your user
Go to Setup → Users → Users and click on your user name.
Scroll down to Permission Set Assignments and click Edit Assignments.
Move HG Insights API Access to Enabled.
Click Save.
Section 5 — Build the Record-Triggered Flow (This is an Example, details will depend on Customer’s trigger workflow)
5.1 Create a new Record-Triggered Flow
Go to Setup → Process Automation → Flows.
Click New Flow.
Select Record-Triggered Flow and click Create.
5.2 Configure the Start element
In the Object field type Lead and select Lead (API name: Lead). This is the standard Salesforce object. Do not select custom objects like Gong__Related_Lead__c or LeanData objects.
Set Trigger to: A record is created or updated.
Set Condition Requirements to: All Conditions Are Met (AND).
Add Condition:
Field: Status
Operator: Is Changed
Value: leave blank — Is Changed does not require a value
Set When to Run the Flow for Updated Records to: Only when a record is updated to meet the condition requirements. This prevents the flow from firing on every single Lead update.
Set Optimize the Flow for to: Actions and Related Records.
Click Done.
5.3 Add a Decision element — Email guard
Before calling the API, add a Decision element to skip any Lead with a blank Email field. This prevents 400 Bad Request errors from the API.
Click the + button below the Start element on the canvas.
Select Decision.
Set Label to: Email Not Blank
Under Outcomes set Outcome Label to: Has Email
Add Condition:
Resource: {!$Record.Email}
Operator: Is Null
Value: {!$GlobalConstant.False}
Click Done. The Has Email path connects to Step 5.4. The default path (no email) has no connection — the Flow ends silently for those records.
5.4 Add the HTTP Callout action
Add the action that calls the HG Insights API. This must be created using New HTTP Callout inside Flow Builder.
Click the + button below the Has Email outcome path.
Select Action.
In the search box type HTTP Callout and select New HTTP Callout.
On Step 1 of the wizard, fill in:
URL Path vs URL field
The URL field (read-only) comes from the Named Credential and shows the base domain: https://api.hginsights.com. The URL Path field is where you type the endpoint path. Together they form the complete URL: https://api.hginsights.com/data-api/v2/scoring/behavioral/live
5.5 Define the request body
On the Set Request Body screen, paste a sample JSON body so Salesforce can infer the data structure.
Paste the following into the Sample JSON Request box:
JSON — SAMPLE REQUEST BODY
{
"email": "test@example.com",
"source": "salesforce"
}
Click Review. The Data Structure panel should show email (String) and source (String).
Click Next.
5.6 Connect and save the HTTP Callout
On the Connect with Sample Response screen, Salesforce makes a live test call to the API.
Click Connect.
You should see Status Code: 202 in the Response panel. This is correct — the API accepted the request.
Option 2: Salesforce Apex Trigger
1. Remote Site Settings - Setup > Security > Remote Site Settings
Salesforce blocks all outbound HTTP calls to unlisted domains. Add the HG Insights API domain before writing any Apex code.
Go to Setup > Security > Remote Site Settings.
Click New Remote Site.
Fill in the fields below and click Save.
2. Named Credential - Setup > Security > Named Credentials
A Named Credential stores the endpoint securely and is referenced in Apex by name, keeping credentials out of code.
Go to Setup > Security > Named Credentials.
Click New (Legacy) and fill in the fields below.
Set Authentication Protocol to No Authentication - the Bearer token is passed as a custom header in Apex.
Click Save.
3. Apex Callout Class - Developer Console > New Apex Class
Create a new Apex class named HGInsightsLiveScoring. The @future(callout=true) annotation is required - Apex triggers cannot make synchronous HTTP callouts.
4. Apex Trigger on Lead - Developer Console > New Apex Trigger
Create a trigger named HGInsightsScoringTrigger on Lead. Update isQualifyingStatus to match Customer’s Lead lifecycle stage values.
Bulk Safety
The trigger collects emails in a Set<String> before firing callouts, so bulk Lead updates result in at most one API call per unique email. The @future method enforces one callout per invocation - this pattern is governor-limit safe.
Endpoint
POST https://api.hginsights.com/data-api/v2/scoring/behavioral/liveRequest Body
Field | Type | Required | Description |
|---|---|---|---|
string | Yes | Email address of the contact to score | |
source | string | System that triggered the request. Accepted values: salesforce, marketo |
{
"email": "user@example.com",
"source": "salesforce"
}Response
The endpoint is asynchronous. It returns 202 Accepted immediately — the score is not in the response body. Processing happens in the background: the contact's activity over the past 90 days is fetched, scored, and the result is written to the matching Salesforce Lead record automatically. No further action is required on your end.
