Skip to main content
The HubSpot integration turns your CRM into a real-time signal source. Every deal movement, contact property update, form fill, and meeting booking becomes a scored signal in Stairoids that can trigger automations across your entire GTM stack. Outgoing actions close the loop by writing changes back to HubSpot — keeping your CRM accurate without manual updates.

​
Prerequisites

Before connecting, make sure you have:
  • A HubSpot account (any paid tier, or a free account with the relevant features enabled)
  • Super Admin or a custom role with Integration permissions in HubSpot
  • Admin access in your Stairoids workspace

​
Connect HubSpot

1

Open Integration Settings

In Stairoids, go to Settings → Integrations and click Add Integration.
2

Select HubSpot

Choose HubSpot from the integration catalog and click Connect with HubSpot.
3

Authorize via OAuth

You’ll be redirected to HubSpot’s OAuth consent screen. Select the HubSpot account you want to connect, review the requested scopes, and click Connect app. Stairoids requests only the scopes it needs — it does not request write access to objects you haven’t enabled outgoing actions for.
4

Choose events to sync

Back in Stairoids, toggle on the incoming signal event types you want to track. You can update these at any time from Settings → Integrations → HubSpot → Configure.
5

Verify the connection

Stairoids performs a test API call and confirms the connection is live. Navigate to your Signal Feed — you should see HubSpot signals appearing within a few minutes.
The HubSpot integration uses OAuth exclusively. You do not need to generate or manage a HubSpot API key. If you disconnect and reconnect, you’ll go through the OAuth flow again to issue fresh tokens.

​
Supported incoming signal events

These are the HubSpot events Stairoids can receive and convert into signals:
EventSignal typeKey properties
Deal stage changeddeal_stage_changeddeal_id, from_stage, to_stage, deal_name, amount
Contact property updatedcontact_property_updatedcontact_id, property_name, old_value, new_value
Email openedemail_opencontact_id, email_subject, campaign_id, opened_at
Email link clickedemail_clickcontact_id, link_url, email_subject, clicked_at
Form submittedform_submitcontact_id, form_id, form_name, page_url
Meeting bookedmeeting_bookedcontact_id, meeting_type, scheduled_at, owner_id

​
Supported outgoing actions

When a Stairoids automation targets HubSpot, it can perform the following actions:
  • Create contact — create a new contact record with mapped properties
  • Update contact property — write a value to any standard or custom HubSpot property
  • Update deal stage — move a deal to a specified pipeline stage
  • Enroll contact in workflow — trigger a HubSpot automation workflow for a contact
  • Add contact to list — add a contact to a static or active HubSpot list

​
Field mapping

Stairoids maps HubSpot properties to its own signal schema automatically for standard fields. When a contact_property_updated signal arrives, the contact’s HubSpot email, firstname, lastname, and company map directly to the Stairoids contact object. For custom HubSpot properties, Stairoids preserves them as key-value pairs under signal.properties. You can configure additional mappings from Settings → Integrations → HubSpot → Field Mapping. Use this to map custom HubSpot properties to Stairoids account or contact fields that your playbooks rely on.
Map your HubSpot lifecycle stage to a Stairoids contact field to use it as a filter condition in your automations. For example, trigger a HeyReach LinkedIn sequence only when the contact is in the “Marketing Qualified Lead” stage.

​
Troubleshooting

  1. Confirm the connection is active under Settings → Integrations → HubSpot. If the status shows Disconnected, re-authorize via OAuth.
  2. Check that the relevant event types are toggled on in the HubSpot configuration panel.
  3. Verify that the HubSpot user who authorized the integration still has the required permissions. If that user was removed or their role changed, the OAuth token may have been revoked — reconnect with a Super Admin account.
  4. HubSpot can occasionally delay webhook delivery during high traffic periods. Wait a few minutes and check whether the signal appears in the Signal Feed.
Outgoing actions write to HubSpot objects using the OAuth token issued during setup. If Stairoids returns a 403 Permission Denied error on an outgoing action:
  1. Go to Settings → Integrations → HubSpot and check which scopes were granted.
  2. Disconnect and reconnect the integration. During the OAuth flow, make sure the authorizing account is a Super Admin — this ensures Stairoids receives all required write scopes.
  3. If you’re trying to enroll contacts in a HubSpot workflow, confirm the workflow is set to Active in HubSpot. Stairoids cannot enroll contacts into draft workflows.
Before creating a new contact, Stairoids checks for an existing match by email address. If duplicates are appearing:
  1. Confirm the incoming signal includes a valid contact.email value. Signals without an email address bypass the deduplication check.
  2. Review your automation’s action configuration — ensure Match existing contact is enabled rather than Always create new.
  3. If the duplicate contact has a different email casing (e.g., User@example.com vs user@example.com), Stairoids normalizes to lowercase before matching. Check whether HubSpot has pre-existing duplicates that Stairoids is reflecting.