Integrating OneSignal with HubSpot

HubSpot and OneSignal have partnered to automate sending web and mobile push notifications and edit data tags for showing in-app messages using Workflows. You can also view OneSignal activity on contacts' timelines and segment users based on OneSignal activity.

You need to use OneSignal independently for more advanced functionality like A/B testing, intelligent delivery, throttling, retargeting etc.


Step 1. Install OneSignal on HubSpot

In HubSpot, click the Marketplace icon in the main navigation bar, then select App Marketplace. Search for and select the OneSignal integration, then click Install app.


Navigate to your OneSignal Dashboard Settings > Keys & IDs to copy-paste the App ID and REST API Key into your app. You can add multiple OneSignal Apps if needed.


Step 2. Map a OneSignal Property to HubSpot

There are two options for mapping users across HubSpot and OneSignal:

Option 1. External User Id (Recommended)

*Required if you want to use both the Send notification and Edit tags Workflow actions in HubSpot.

Within HubSpot Settings > Integrations > Connected Apps > OneSignal > Your preferences select the HubSpot Contact property you wish to match to OneSignal. This should be available client-side and accessible to the OneSignal SDK.


Using the OneSignal SDK on your app or website, set the External User Id to match the selected HubSpot Contact Property. It is recommended to call this method whenever the user logs into your Website, Android, and/or iOS Apps.

Option 2. OneSignal setEmail method

*Only available for Send push notification Workflow action in HubSpot.

Use the OneSignal SDK setEmail method to pass in the current user's email address. It is recommended to call this method whenever the email is provided across your Website, Android, and/or iOS Apps.

Step 3. Defining the HubSpot Workflow

Within HubSpot, navigate to Automation > Workflows and click Create workflow.

In the left panel, select Contact-based and Next in the top right.
Set your enrollment triggers, then click + to add an action.

In the right panel, under OneSignal, choose an option:

Send OneSignal notification Workflow Action


Select your OneSignal App and matching option. You will then have the option to send a push notification using a template or a custom configuration.

Use templatesYou can create Templates in the OneSignal Dashboard for your common use cases. Templates created will be pulled into HubSpot.
Use custom configurationYou can also select “Create custom message” as an option and use various fields (Title, Subtitle, Message, Image URL, Launch URL) to create the push notification.

The benefit of this option is you can also use HubSpot contact data (e.g., First Name, favorite color) to personalize the notification fields. OneSignal will correctly format the message for different devices and messaging channels.

Click Save when finished.

Edit OneSignal device's tags Workflow Action

OneSignal uses Data Tags for adding custom properties onto users. Tags can be used to add HubSpot Contact Properties into OneSignal for Message Personalization and/or Segmentation and sending In-App Messages.

Select your OneSignal App and enter a JSON string with the format { "key" : "value" } and press Save.


Within the OneSignal Dashboard Audience, select New Segment. Give it a name based on the tags selected and select the User Tag filter.

Input the "key" and "value" set in HubSpot and click Create Segment.


Navigate to Messages > In-App and select New In-App.

Name your new IAM so you can identify it in the dashboard.

Under "1. Audience" select Show to Particular Segment(s) and select your newly created segment.

As users go through the HubSpot workflow, they will get tagged which will put them immediately into this segment. Note: getting a tag does not trigger the IAM. More details below in Trigger Options.


For "2. Message" follow the Sending In-App Messages Guide for details on creating your In-App Message.

Trigger Options

In-App Messages need to be triggered to show on the device. Triggers can be time-based or programmatic. Note: a tag is not a trigger. If the tag is added while the device is currently using the app, the IAM will not display. The In-App Message will show the next time the user returns to your app in a new session. New sessions are counted upon the app being out-of-focus for 30 seconds.

Under "3. Triggers" you can set the IAM to display based on the following triggers:

  • On App Open
  • Session Duration > or < a set number of seconds
  • Duration since another IAM was shown
  • Programmatically with the OneSignal SDK

Triggers can be combined with "AND" operators and separated into multiple options with "OR" operators.


See How to trigger an IAM guide for more details.

Step 4. Workflow History

Navigate to your HubSpot Workflows and within the desired Workflow select the History tab.
Here you will be able to see which contacts were sent notifications and updated tags.


Error Messages

"No OneSignal Devices matched this contact's external_user_id property [THE_VALUE_OF_EXTERNAL_ID_HUBSPOT_CONTACT_PROPERTY]"

In these cases, the targeted user does not have a matching External User Ids.

"No OneSignal Devices matched any of this contact's email addresses [[email protected]]"

The targeted user does not have a matching email address using the setEmail method on the OneSignal SDK.


What data is shared between HubSpot and OneSignal?

HubSpotDirectionOneSignal AppDescription
Contacts➡️UsersHubSpot Contact email addresses are used to match OneSignal Users / Devices
Events⬅️MessageOneSignal notifications are logged on Contact Activity Timeline and available for List segmentation in HubSpot
Workflows⬅️Notification TemplatesOneSignal Notification Templates are available for selection in HubSpot Workflows

Additional Details

Please check HubSpot for more information.