> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> Sync advocate share links into HubSpot contact records, and send HubSpot form completions and deal outcomes to Extole for referral tracking and reward scoring.

Extole connects to HubSpot in two directions: syncing advocate identity and share links into HubSpot contact records, and pulling HubSpot activity (form completions, deal outcomes) into Extole to track and reward referrals.

## Prerequisites

| Requirement | Description |
| - | - |
| HubSpot account | An active HubSpot account. |
| Extole account | An Extole account with access to the **Partners** section. |
| Operations Hub Professional or higher | Required only if using the Extole HubSpot App — its serverless functions depend on this tier. |

<Tip>
  The [Extole CLI](/technical/extole-ai-tools/extole-cli/index) ([GitHub](https://github.com/extole/extole-cli)) and the [HubSpot CLI](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli) ([GitHub](https://github.com/HubSpot/hubspot-cli)) aren't required, but they make a couple of steps below faster: the Extole CLI to duplicate the `hubspot_share_controller` trigger onto a campaign, and the HubSpot CLI to create and deploy a custom serverless function.
</Tip>

## Recommended Integration

The Extole HubSpot App and `hubspot_integration` — an integration you configure in your Extole account — work together to provide advocate sync, referral tracking, and deal scoring.

### Extole HubSpot App

<Info>
  Currently distributed as a private app. This section will be updated once it's listed on the HubSpot Marketplace.
</Info>

The app is a HubSpot UI Extension with three features:

**Configure Events** — Defines record-triggered events that fire to Extole when HubSpot records change. Admins create a workflow trigger in HubSpot's workflow builder; the app provides the action step that calls Extole with a configured event name and mapped properties. Supports Contact, Deal, Company, Ticket, and custom objects, with trigger types Record Created, Field Changed, and Field Value.

A common use case is deal-based referral rewards: a workflow on the Deal object triggers on `dealstage = closedwon`, with **Include associated contact data** enabled so the event carries both the deal's own properties (such as `amount`) and the contact's identity and advocate code in one payload.

**Manage Advocate Codes** — Generates a JavaScript snippet for the client's site. When a friend arrives via an advocate's share link, the snippet reads the shareable code from the URL, persists it, and injects it as a URL query param on any page with a HubSpot form so the form's hidden `advocate_code` field is pre-populated at submission. Requires HubSpot-native forms; doesn't work with third-party form tools.

**Manage Share Links** — Automatically generates Extole share links for contacts and writes them to a configurable contact property, with auto-generation on contact create and bulk backfill for existing contacts. Includes **Anonymous Advocate Sync**: the reverse-direction webhook endpoint that Advocate Sync (below) sends requests to.

### Advocate Sync

Two pieces work together to push advocate data into HubSpot:

* **`hubspot_integration`** — an integration in your Extole account that holds your HubSpot connection settings: the webhook URL and shared secret.
* **`hubspot_share_controller`** — a trigger you attach to each campaign, so it fires whenever that campaign's advocate journey creates a share link.

Together they dispatch the advocate's identity and share link to a HubSpot endpoint, which upserts the advocate's HubSpot contact: updating the share link and code on the existing contact if the advocate is already a HubSpot customer, or creating a new contact for them if not.

| Field | Source |
| - | - |
| `email` | Advocate's email |
| `first_name` | Advocate's first name |
| `last_name` | Advocate's last name |
| `share_link` | Advocate's share link |
| `shared_secret` | The Client Key value configured on the integration |

Set it up:

1. In **Security Center** > **Keys**, create a Client Key (Type: `Webhook`, Algorithm: `Password`) holding the shared secret from the app's Anonymous Advocate Sync section.
2. In the integration's **Configuration** tab, set **Webhook URL** to the app's Anonymous Advocate Sync endpoint, and **Shared Secret** to reference that Client Key.
3. Duplicate the `hubspot_share_controller` trigger into each marketing campaign that should sync advocates:

   ```bash theme={null}
   extole components duplicate <hubspot_share_controller-component-id> --target-campaign <target-campaign-id>
   ```
4. On the duplicated copy, set **Journey Names** to the campaign's real advocate journey (for example, `ADVOCATE`) and **HubSpot Webhook** to the integration's Dispatch Webhook setting. Publish the campaign.

## Legacy and Custom Setups

These are the setups Extole used for this integration before the HubSpot App existed. They're kept here for accounts that already built things this way, or that need finer control over the HubSpot side than the App provides.

### Advocate Sync — Custom Endpoint

Use the same `hubspot_share_controller` trigger from Recommended Integration above, but pair it with a HubSpot endpoint you build yourself instead of the App's Anonymous Advocate Sync endpoint.

1. Create the function:

   ```bash theme={null}
   hs cms function create <name> --functions-folder api.functions --filename advocate-sync.js --endpoint-method POST --endpoint-path api/<path>
   ```
2. Implement the handler to verify `shared_secret` and upsert the contact via the HubSpot CRM API, using a Private App access token or Service Key (contacts read/write scope) added as a function secret.
3. Upload it:

   ```bash theme={null}
   hs cms upload api.functions api.functions
   ```
4. The resulting URL is `https://<account-id>.hs-sites-<region>.com/_hcms/api/<path>`. Use this as the integration's **Webhook URL**, as in the section above.

### Advocate Sync — Direct API Calls

Extole calls HubSpot's Contacts API directly, with no integration or trigger involved.

1. In your HubSpot developer account, create a private app with a `crm.objects.contacts.write` scope and generate a Bearer Token.
2. In Extole's **Tech Center** > **Outbound Webhooks**, create a Client Key: select **Webhook** as the Key Type, **Password** as the Algorithm, and paste the Bearer Token as the key value.
3. Create a webhook: Type **Generic**, Client Key set to the key from step 2, API URL `api.hubapi.com/crm/v3/objects/contacts`, method **POST**.
4. Attach the webhook to the point in your Extole campaign that fires when a share link is created — the advocate journey's SHAREABLE event.

A successful dispatch returns a `201` with a body resembling:

```json theme={null}
{
  "properties": {
    "email": "test123@example.com",
    "share_code": "test123",
    "share_link": "share.test123@example.com",
    "extole_app_type": "hubspot"
  }
}
```

Configure HubSpot to capture and populate contact records with the custom `share_link` and `share_code` properties.

### Referral Tracking on Form Completion

<Info>
  If you're using the Extole HubSpot App, **Manage Advocate Codes** already pre-fills `advocate_code` on your forms, and **Configure Events** can fire the resulting event to Extole without a custom workflow webhook — see Extole HubSpot App above. The steps below build both by hand.
</Info>

Track friends who complete a HubSpot form.

1. Add a custom field to the HubSpot contact record and lead form, with internal name `advocate_code`.
2. Add Extole's Core and Event [JavaScript tags](/technical/platform-integrations/javascript-sdk/index) to the lead form to track referral attribution even when the friend doesn't manually enter a code.
3. In HubSpot, create a workflow that triggers a webhook every time a form is completed with `advocate_code` populated, or the field is populated on a contact record.
4. Configure the workflow webhook: method **POST**, URL `api.extole.io/v5/events`, authentication **API Key** (an Extole access token), with a customized request body:

```json theme={null}
{
  "event_name": "signed_up",
  "data": {
    "email": "{{email}}",
    "advocate_code": "{{advocate_code}}",
    "first_name": "{{first_name}}",
    "last_name": "{{last_name}}",
    "event_date": "{{date}}",
    "partner_conversion_id": "{{id}}",
    "extole_app_type": "hubspot"
  }
}
```

### Deal or Conversion Scoring

<Info>
  If you're using the Extole HubSpot App, **Configure Events** already covers this — see the deal-based referral rewards example under Extole HubSpot App above. The steps below build the workflow webhook by hand.
</Info>

Repeat the workflow webhook setup above with the event name changed to `converted`, adding keys for `product` and `amount` to pass deal details. Configure a matching rule in the Extole campaign to reward the advocate once the criteria are met.

## FAQs

**Does the advocate need to already exist as a contact in HubSpot?**
No. The Anonymous Advocate Sync endpoint upserts the contact by email, creating a new contact if one doesn't exist.

**What happens if Advocate Sync's Webhook URL or Shared Secret is invalid?**
The dispatch fails and retries per the webhook's retry schedule. After retries are exhausted, the dispatch is marked failed.

**Can I use the app and a legacy or custom setup together?**
Each capability (advocate sync, referral tracking, deal scoring) is independent — an account can use the app for some and a legacy or custom setup for others.


## Related topics

- [Create Share Link on an Event](/technical/platform-integrations/extensions/create-share-link-on-an-event.md)
- [Build a Loyalty Program](/technical/platform-integrations/extensions/reward-bank/loyalty-program-guide.md)
- [2026](/news/newsletters/2026.md)
- [Upload and Email an Audience](/guides/audiences-and-segmentation/my-audiences/upload-and-email-an-audience.md)
- [Extole CLI](/technical/extole-ai-tools/extole-cli/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.