HubSpot Integration Overview & Setup

What the Integration Does

The HubSpot integration syncs referral data between your HubSpot account and Ambassador 3 in real time. Here's what it supports:

Sync Referred Contacts (optional setting) — When a new contact is created in HubSpot with a Referring Shortcode, Ambassador automatically creates them as a prospect contact and establishes a Referral Attribution between them and the referring Advocate. From there, you can use Ambassador Automations to move them into the first stage of a Journey and notify the Advocate.

Sync Referred Deals — When a deal is created in HubSpot, Ambassador creates an Order for the referred contact and populates the hubspot_dealstage field. Use Automations to update Journey stages, send referral notifications to the Advocate, and optionally create pending or approved rewards based on deal status.

Sync Referred Deal Stage Updates — When a deal stage changes in HubSpot, Ambassador updates the hubspot_dealstage field on the corresponding Order. From there, Automations can update the contact's Journey stage, create or approve rewards, and send reward notifications.

Enroll Referred Contacts as Advocates — Use Automations to enroll a referred contact as an Advocate at whatever deal stage makes sense for your program (e.g., when a deal is closed-won).

Integration Setup

Step 1 — Create a Private App in HubSpot

In your HubSpot account, go to Settings > Integrations > Private Apps and click Create a private app. (If you already have one for Ambassador, you can edit it.)

Step 2 — Configure Basic Info and Scopes

On the Basic Info tab, give the app a descriptive name (e.g., "Ambassador Integration"). Then click the Scopes tab and grant these permissions:

• crm.objects.companies.read
• crm.objects.contacts.read
• crm.objects.contacts.write
• crm.objects.deals.read
• crm.objects.deals.write
• tickets

Step 3 — Set the Webhook Target URL

Click the Webhooks tab. In the Target URL field, paste:

https://api.getambassador.com/integrations/webhooks/hubspot/

Step 4 — Create Contact Subscriptions

Under Event Subscriptions, add the following for the Contact object:

• contact.creation
• contact.deletion
• contact.propertyChange — First name, Last name, Email, Phone Number, Company Name, Street Address, City, State/Region, Postal Code, Country/Region, Date of birth, Job Title

Step 5 — Create Deal Subscriptions

Add the following for the Deal object:

• deal.deletion
• deal.propertyChange — Pipeline, Deal Stage

Step 6 — Save and Copy Credentials

Click Create app to save your configuration. Copy the generated Access Token and Client Secret, then paste them into the authentication fields in Ambassador under Integrations > HubSpot to complete the connection.

Step 7 — Verify Ambassador Fields in HubSpot

Once the integration is connected, Ambassador automatically creates these custom fields in HubSpot:

• Contact object: referring_shortcode (Referring Shortcode)
• Deal object: short_code (Ambassador Short Code)

How Deal Sync Works

When a Deal is created in HubSpot, Ambassador looks for a Referring Shortcode on the Deal first. If it finds one, it syncs the associated contact. If not, it checks the Deal's associated contacts for a Referring Shortcode. If none is found, the sync is skipped.

When a successful Deal sync occurs, Ambassador automatically:

• Creates the referred contact in Ambassador (as Prospect status) if they don't already exist
• Creates an Order for the referred contact
• Creates a Referral Attribution between the referred contact and the referring Advocate

No Automations are needed for these three steps — they happen automatically. You'll use Automations from there to handle Journey stage updates, reward creation, and communications.

Using Journeys with HubSpot Deal Stages

If you want to track referral pipeline progress using Journeys, the recommended approach is to create a Journey with stages that map to your HubSpot Deal stages (or the subset of stages that matter most). Then:

• Use the Automation trigger Order Created to move the contact into the first Journey stage
• Use Order Updated + an If/Else condition checking hubspot_dealstage to advance the contact through subsequent Journey stages
• Trigger reward creation or approval at the appropriate deal stage

If you're using the optional "Sync Referred Contacts" setting, the contact may already be in the first Journey stage before the Deal is created. In that case, the Deal creation will still create an Order, and your Order-based Automations can continue advancing them through the Journey from there.

Good to Know

• The HubSpot integration requires an active private app in HubSpot — Ambassador uses webhooks to receive real-time updates.
• If you don't see the referring_shortcode field on your HubSpot Contact or Deal objects after connecting, contact support@getambassador.com and we'll help troubleshoot.
• You don't need to use every sync feature — enable only the settings that match your program workflow.
• Related articles: Referral Attribution Overview, Journeys Overview, Automations Overview, Orders Overview, Integrations Overview