HubSpot

The Userflow-HubSpot integration creates a powerful bridge between your customer data and onboarding experiences through bidirectional, near real-time syncing. This integration enables you to deliver personalized onboarding content based on HubSpot data and automatically track user engagement within HubSpot.

What this integration does

Sync customer data for personalization: HubSpot contact, company, deal, and custom object properties sync to Userflow, enabling you to target flows based on customer segments, subscription tiers, industry, or any other HubSpot data.

Track engagement automatically: Userflow-generated events such as Flow Started, Checklist Task Completed, and survey responses stream directly into HubSpot as Timeline Events. View these on contact profiles and trigger automated workflows, such as sending follow-up emails when users complete onboarding steps.

Maintain data consistency: Changes in either system sync within seconds, ensuring your team always works with up-to-date information across both platforms.

Ready to get started? Find setup instructions below, or visit our HubSpot marketplace listing for a complete demo video.

How it works

The integration operates through flexible object mappings between HubSpot and Userflow. You can connect HubSpot contacts to Userflow users, HubSpot companies to Userflow companies, or create custom mappings based on your data structure.

Supported HubSpot objects

• Contacts: Individual users and customers

• Companies: Organizations and accounts

• Deals: Sales opportunities and transactions

• Custom objects: Any custom data structures you've created

Matching and syncing

Objects are matched using ID fields you specify during setup. Common approaches include matching by email address or using a shared ID from your backend database. Field syncing works bidirectionally—bring HubSpot properties into Userflow for targeting, or send Userflow data such as NPS scores back to HubSpot.

Near real-time performance

Syncing happens in near real-time with minimal delay:

• Userflow changes: Reflected in HubSpot in under 1 second

• HubSpot changes: Typically appear in Userflow within 3-10 seconds

Objects sync immediately when created or updated in either system; no need to wait for scheduled jobs.

Smart syncing rules

The integration only syncs objects that exist in both systems, preventing the creation of unwanted data. For example, HubSpot contacts that receive only newsletters won't be created as corresponding Userflow users unless they use your product.

HubSpot properties appear on Userflow user and company profiles, clearly marked with the HubSpot sprocket icon for easy identification:

You can use them in auto-start conditions to target users based on HubSpot properties:

When enabled, Userflow tracks specific events—such as flow starts and checklist task completions—and posts them to the Activity tabs of contacts and companies in HubSpot. To view these activities, first enable Userflow tracking by clicking the Filter activity button:

Then they’ll appear like this:

You can also use these events in workflows, for example, to send an email when a user completes a checklist task:

You can even filter on event attributes, such as the name of the checklist task that was completed:

Important: HubSpot account and Userflow environment pairing

Each HubSpot-Userflow integration connects one HubSpot account to one Userflow environment. This means you'll need to complete the setup process separately for each environment you want to integrate.

Best Practice for Production vs. Staging

For your production setup, integrate your main HubSpot account with your Production Userflow environment.

⚠️ Critical for Staging Environments

If you're using a Staging Userflow environment to test the HubSpot integration, create a separate test HubSpot account for this purpose. Using your main HubSpot account with a Staging environment will cause test timeline events to appear in your production HubSpot data, which could affect your live customer records.

Setup guide

1. Sign in to Userflow, then use the top-right company/environment menu to select the environment you want to integrate with HubSpot.

2. Go to Settings > Integrations. Then click Add integration.

3. Find and click HubSpot in the list:

4. Click Add HubSpot (activate/upgrade your plan if you don’t yet have access):

5. Click Connect with HubSpot. In the pop-up window that opens, pick the HubSpot account you want to sync with the current Userflow environment.

6. Next, we need to instruct the integration on how to map HubSpot objects to Userflow objects. Click Set up a new mapping between HubSpot and Userflow objects.
   

7. In the dialog that appears, pick the HubSpot object type and the Userflow object type you want to sync. For example: HubSpot contacts and Userflow users. Then click Continue.
   

8. Choose how we should match objects from HubSpot with objects in Userflow.

   • If you’re syncing HubSpot contacts with Userflow users, you have two options:

     • Via email address, where a HubSpot contact’s email address must match a Userflow user’s email address. Pick “Email” in both dropdown fields.

     • Via a HubSpot ID property, which must match the user ID your Userflow.js snippet passes to userflow.identify(userId). This requires you to integrate your backend with HubSpot to store the user ID as a contact property.

   • If you’re syncing with Userflow companies:

     • Requires your Userflow.js installation to call userflow.group(companyId), and the selected HubSpot company ID property must match this same companyId.

9. Choose the fields you want to sync from HubSpot to Userflow. Note that you’re also able to pick fields from associations of the mapped HubSpot object. For example, when syncing HubSpot contacts, you can also select company fields in the dropdown. The integration will take the value from the contact’s company.

10. Choose the fields you want to sync from Userflow to HubSpot. Once you save, the appropriate properties prefixed with userflow_<object>_ will automatically be created in HubSpot under a property group named “Userflow.”

11. If you want Userflow to post timeline events to HubSpot objects’ Activity tab when, for example, flows are started or checklist tasks are completed, you can either stream all events or select events to stream:

    1. Use the toggle switch to turn Stream events to ON. Note that only some HubSpot objects support receiving events.

    2. Select either Stream all events or Select events to stream, and select each event you want to stream.
       

12. Finally, click Save mapping.

    

13. Userflow will now sync with HubSpot every time objects are created/updated in either system. Existing objects have not yet been synced. Click Run full sync to start an initial full sync of all objects.

14. The UI shows you a running progress and a green checkmark when it’s done. If you later change your mappings, we recommend running a full sync again to ensure all existing users are updated. We also run a full sync periodically (currently every ~24 hours) to ensure we haven’t missed any updates from HubSpot.

15. 

16. You can add multiple object mappings. For example, HubSpot contacts <—> Userflow contacts and HubSpot companies <—> Userflow companies.

Troubleshooting HubSpot Integration

Integration Not Connecting

Symptom: The OAuth connection fails when you click "Connect to HubSpot."

Causes:

• Insufficient HubSpot permissions: You need Admin or Super Admin access in HubSpot to authorize the integration

• Pop-up blocked: The OAuth window was blocked by your browser

Fix:

1. Check your HubSpot role: Settings → Users & Teams in HubSpot. Look for your name and confirm "Admin" or "Super Admin."

2. If you're not an admin, ask a HubSpot admin to complete the connection.

3. If pop-up was blocked: Allow pop-ups from Userflow and try again.

Data Not Syncing to HubSpot

Symptom: Userflow events or user attributes aren't appearing in HubSpot.

Common Causes:

1. Field mapping not configured

• Go to Settings → Integrations → HubSpot → Field Mapping in Userflow

• Make sure Userflow attributes are mapped to HubSpot properties

• Fix: Map each Userflow attribute you want to sync (e.g., flow_completed → HubSpot custom property userflow_flow_completed)

2. HubSpot properties don't exist

• Userflow can only sync to existing HubSpot properties

• If you map to a property that doesn't exist in HubSpot, the sync will fail silently

• Fix: Create the property in HubSpot first (Settings → Properties in HubSpot), then map it in Userflow

3. API rate limit

• HubSpot limits API calls. If you're sending a lot of data at once, some syncs may be delayed or dropped

• Fix: Check Settings → Integrations → HubSpot → Sync Log in Userflow for rate limit errors. If you see them, contact support@userflow.com.

HubSpot Connection Lost / Needs Re-Authorization

Symptom: Integration was working, now shows "Not connected" or "Authorization expired."

Cause: HubSpot OAuth tokens expire periodically (typically every 6 months), or the HubSpot admin who authorized the connection was removed from the account.

Fix:

1. Go to Settings → Integrations → HubSpot

2. Click Reconnect

3. Complete OAuth flow again

Specific Events Aren't Syncing

Symptom: Some Userflow events sync to HubSpot, but others don't.

Causes:

• Event isn't mapped: Go to Settings → Integrations → HubSpot → Event Mapping and confirm the event is listed and mapped to a HubSpot property or timeline event.

• HubSpot property type mismatch: If you're mapping a Userflow date to a HubSpot text field, the sync will fail. Property types must match (text → text, number → number, date → date).

Fix:

1. Verify event mapping in Userflow

2. Verify property types in HubSpot (Settings → Properties)

3. Update mapping or property type, then test with a new event

Still Having Issues?

If you've tried all of the above:

1. Check the Sync Log: Settings → Integrations → HubSpot → Sync Log for specific error messages

2. Copy any error messages

3. Contact support@userflow.com with:

   • Your HubSpot account ID

   • The error message

   • Which events or properties aren't syncing

Stopping the integration

1. Find your HubSpot integration in Userflow under Settings -> Integrations.

2. Click the three-dot button in the top right.

3. Click Disconnect. Event streaming and property sync will stop immediately.

4. Finally, uninstall the Userflow app in your HubSpot account by following HubSpot’s instructions here.