HubSpot Field Mapping

What It Does

HubSpot Field Mapping allows you to:

• Map standard fields like name, email, and phone automatically between ILLIXIS and HubSpot
• Map custom properties from HubSpot to ILLIXIS subscriber fields
• Configure stage mappings to trigger email sequences when deals move through your pipeline
• Sync contact data in real-time via webhooks

When a deal changes stages in HubSpot, ILLIXIS pulls the associated contact data using your field mappings, then triggers the configured automation.

Prerequisites

Before configuring field mapping, you must:

1. Connect HubSpot via OAuth at Settings > Integrations > CRM tab
2. Have an active HubSpot subscription with API access
3. Have deal pipelines configured in HubSpot

Accessing Field Mapping

Step 1: Navigate to HubSpot Settings

Go to Settings > Integrations.

Click the CRM tab.

Find the HubSpot card and click Settings (or Connect if not yet connected).

Step 2: View Stage Mappings

After connecting, you'll see your HubSpot pipelines listed with their stages.

Each stage shows:

• Pipeline name and stage name from HubSpot
• Current mapping action (sequence enrollment or pipeline stage move)
• Save button to update mapping

Default Mappings

When syncing contacts from HubSpot deals, these fields are mapped automatically:

| HubSpot Property | ILLIXIS Field | Notes |
|------------------|---------------|-------|
| firstname | First Name | Standard contact property |
| lastname | Last Name | Standard contact property |
| email | Email | Required - used for matching |
| phone | Phone | Optional |

These mappings work out of the box when contacts are synced via webhook or manual refresh.

Adding Stage Mappings

Stage mappings define what happens when a deal moves to a specific stage in HubSpot.

Step 1: Refresh Pipelines

Click Refresh Pipelines to pull the latest pipeline and stage data from HubSpot.

This fetches all deal pipelines configured in your HubSpot account.

Step 2: Configure a Stage Action

For each HubSpot stage you want to automate:

1. Find the stage in the list under its pipeline
2. Click the dropdown next to the stage name
3. Select an action:

Enroll in Sequence:

• Select an active ILLIXIS email sequence
• When a deal enters this stage, contacts are enrolled
• Previous sequences can be stopped automatically (configurable)

Move to ILLIXIS Stage:

• Select an ILLIXIS pipeline and stage
• The lead moves through your internal pipeline
• Useful for mirroring CRM progression

No Action:

• Select "No action" to skip automation for this stage
• The stage change is still logged for reference

Step 3: Save Mapping

Click the checkmark button next to the dropdown to save.

A green confirmation appears when saved successfully.

Sync Behavior

When Data Syncs

Real-time via webhooks:

• Deal stage changes in HubSpot trigger immediate sync
• Requires webhook configuration (see below)
• Most reliable for automation triggers

Manual refresh:

• Click "Refresh" on the HubSpot settings page
• Pulls latest pipeline data
• Does not trigger enrollments

Webhook Configuration

To receive real-time updates:

1. Go to your HubSpot Developer Account
2. Navigate to Webhooks
3. Create a new webhook:

• URL: https://app.illixis.io/marketing-automation/webhooks/hubspot/
• Event: deal.propertyChange
• Property: dealstage

4. Click Create

Webhook signatures are verified using HMAC-SHA256 for security.

Contact Matching

When a deal changes stages:

1. ILLIXIS fetches contacts associated with the deal
2. Contacts are matched by email address
3. If no match exists and "Create lead if missing" is enabled, a new lead is created
4. Field mappings are applied to populate/update contact data
5. The mapped action (sequence enrollment or stage move) is triggered

Tips for Best Results

• Start with key stages: Don't map every stage. Focus on stages where automation adds value (e.g., "Qualified," "Demo Scheduled," "Proposal Sent").
• Use descriptive sequence names: When selecting sequences, clear names like "Pre-Demo Education" make mappings easier to understand.
• Test with a single deal: Before going live, move one test deal through stages to verify mappings work correctly.
• Check sequence status: Ensure mapped sequences are Active (not Draft or Paused). Inactive sequences won't send emails.
• Review activity logs: After testing, check the lead's Activity Timeline to confirm events were logged correctly.
• Keep pipelines in sync: If you rename stages in HubSpot, re-run "Refresh Pipelines" to update ILLIXIS.

Troubleshooting

Contacts Not Syncing

Check webhook configuration:

• Verify URL is exactly https://app.illixis.io/marketing-automation/webhooks/hubspot/
• Confirm webhook is subscribed to deal.propertyChange event
• Check HubSpot webhook logs for delivery errors

Check deal has contacts:

• Open the deal in HubSpot
• Verify at least one contact is associated with the deal
• ILLIXIS can only sync contacts that are linked to the deal

Sequence Not Triggering

Check mapping exists:

• Go to HubSpot Settings in ILLIXIS
• Confirm the specific stage has a sequence mapped
• Save the mapping again if unsure

Check sequence is active:

• Go to Email Automation > Sequences
• Find the mapped sequence
• Status should be "Active" (green badge)

Token Expired

If you see "Token needs refresh" or connection errors:

1. Click Disconnect on the HubSpot card
2. Click Connect to re-authorize
3. Your stage mappings are preserved
4. Verify connection shows "Connected"

Related Features

• CRM Integrations - Overview of all CRM platforms
• Lead Pipeline - Manage leads and pipeline stages in ILLIXIS
• Visual Sequence Builder - Create email sequences to map to stages
• Email Automation Triggers - Other ways to trigger sequences

Automation Schedule

Field mapping syncs happen in real-time based on webhook events. No scheduled batch processing is used.

| Event | Timing |
|-------|--------|
| Deal stage change | Real-time (webhook) |
| Pipeline refresh | On-demand (manual) |
| Token refresh | Automatic when expired |