HubSpot deprecated the original third-party OneSignal app in December 2024. OneSignal now provides its own HubSpot app with expanded functionality. If you used the previous integration, see the migration steps below.
Migrating from the legacy HubSpot integration
Install the new integrationActivate the HubSpot integration from the OneSignal dashboard under Data > Integrations as described in Connect HubSpot to OneSignal below.Migrate your workflowsWe recommend creating a new workflow to test the new integration before replacing actions in your existing workflows.
Clone your workflow: On the HubSpot Workflows page, click Clone next to your existing workflow.
Remove triggers: In the cloned workflow, remove all enrollment triggers so it does not fire automatically when published.
Replace legacy actions: Remove each legacy OneSignal action and replace it with the new version. If both apps are installed, the legacy app shows “Built by HubSpot”. Use the one that does not.
When both apps are installed, use the OneSignal action that does not say 'Built by HubSpot'.
Test with a single contact: Save and publish the workflow, then manually enroll one test contact. Check the enrollment history to verify actions completed successfully.
Example migrated HubSpot workflow.
Replace or update: After confirming the workflow works correctly, either replace the original workflow with the clone or apply the same changes to the original.
If you encounter errors during migration, contact support@onesignal.com.
In OneSignal, go to Data > Integrations > Catalog and select HubSpot.
The HubSpot integration card on the OneSignal Integrations page.
Click Settings > Authenticate, then select your HubSpot account and log in.
You can only connect one HubSpot account to each OneSignal app. If you have a testing environment, set up another OneSignal app for testing.
Select which HubSpot account to connect to this OneSignal app.
After agreeing to the terms and selecting Connect app, you are redirected back to OneSignal. The HubSpot integration in Data > Integrations now shows your connected account.
To link HubSpot contacts to OneSignal users, set the External ID in OneSignal to a value that matches a unique property in HubSpot (e.g., a user ID or email address).Set External ID using the SDK login method in your app or website. Choose a property that is readily available in both your app and HubSpot so matching is reliable.
See Users and Subscriptions for details on identity and subscription management.
In HubSpot, go to Automation > Workflows and click Create workflow. Select Contact-based and configure your enrollment triggers.To add a OneSignal action, click + in the workflow editor and search for “OneSignal”.
OneSignal workflow actions in HubSpot.
Every OneSignal action requires two fields:
Setting the OneSignal App and External ID in a workflow action.
OneSignal App: the app you connected during setup.
External ID: the HubSpot contact property whose value matches the OneSignal user’s External ID (set via the SDK login method).
The Create User action creates a User in OneSignal when a contact passes through the workflow. Use this to keep OneSignal and HubSpot in sync as new contacts are added.If the following HubSpot properties are set, OneSignal automatically creates corresponding Subscriptions:
Email → creates an email Subscription in OneSignal
Phone number → creates an SMS Subscription in OneSignal
You can also set the External ID and tags within the Create User node.
OneSignal Create User node in a HubSpot workflow.
If your OneSignal app has Double Opt-in enabled, new SMS Subscriptions automatically receive an opt-in message. You can disable this in the Create User node. The SMS Subscription will still be created, but the user will not be subscribed until they opt in separately.
{ "welcome": "1", "name": "<First Name property>" }
You can inject any HubSpot contact property as a tag value by using HubSpot’s property token inserter in the workflow editor. For example, add a user’s first name as a tag so you can personalize messages in OneSignal.
If you do not select a template, you can compose a push notification directly in the workflow action using the Title, Subtitle, Message, Image URL, and Launch URL fields. Email and SMS/RCS messages are only available via templates.The form fields option allows you to inject HubSpot contact properties (e.g., First Name) to personalize the notification content.
In-app messages cannot be sent directly from a HubSpot workflow. Instead, use HubSpot to tag users, then target those users with a segment-based in-app message in OneSignal.
1
Tag users from HubSpot
In your HubSpot workflow, use the Edit Tags action to set a tag on contacts. For example: { "hubspot_campaign": "spring_promo" }.
2
Create a segment in OneSignal
In the OneSignal dashboard, go to Audience > Segments and click New Segment. Add a User Tag filter matching the tag key and value set by HubSpot (e.g., hubspot_campaign is spring_promo).
3
Create the in-app message
Go to Messages > In-App and create a new in-app message. Under Audience, select Show to Particular Segment(s) and choose the segment you created.As users pass through the HubSpot workflow and receive the tag, they are added to the segment immediately.
4
Configure the trigger
Tags do not trigger in-app messages on their own. If the tag is set while the user is actively using the app, the in-app message does not display until the next session (a new session starts after the app is in the background for 30+ seconds).Available triggers:
On app open: displays the next time the user opens the app.
Session duration: displays after a set number of seconds in-session.
Time since last in-app message: prevents back-to-back messages.
Programmatic: trigger from your app code using the OneSignal SDK.
HubSpot workflows combine enrollment triggers (the event that starts the workflow) with OneSignal actions (what happens to the user in OneSignal). Below are recommended patterns for common use cases.
Target a specific audience with an in-app message triggered by a HubSpot list or form.
Step
Type
Configuration
Enrollment trigger
HubSpot
Contact becomes a member of a static or active list (e.g., “Spring Sale Eligible”)
Action 1
OneSignal: Edit Tags
{ "promo": "spring_2025" }
Then follow the Send in-app messages steps to create a OneSignal segment matching promo = spring_2025 and configure an in-app message for that segment.To remove users from the campaign after it ends, create a second workflow that deletes the tag:
Check the error message: Expand the failed action in the HubSpot workflow enrollment history. The error message often indicates the cause (e.g., “User not found,” “Invalid app ID”).
Verify the External ID: Confirm the HubSpot contact property used as the External ID matches a user in OneSignal. Check the user’s profile in OneSignal > Audience > Users and search by External ID.
Confirm the integration is active: Go to OneSignal > Data > Integrations > HubSpot and verify the connection status is active.
Check subscriptions: The user must have an active subscription for the channel you’re sending on (push, email, or SMS/RCS). Verify this in the user’s profile in OneSignal under Subscriptions.
Check segment membership: If you’re using a template with segment targeting, confirm the user belongs to the targeted segment.
Review message reports: In the OneSignal dashboard, go to Messages, find the message, and check its delivery report to see if the message was delivered, dropped, or errored.
Verify External ID matching: If the External ID in the workflow does not match an existing OneSignal user, the Edit Tags action silently fails. Use the Create User action before Edit Tags to ensure the user exists.
Check JSON format: Tags must be a valid JSON object. Common mistakes include missing quotes around keys or values, trailing commas, or using single quotes instead of double quotes.
Check for empty values: Setting a tag value to "" deletes the tag. Verify that HubSpot contact properties being injected are not blank.
What data is shared between HubSpot and OneSignal?
HubSpot
Direction
OneSignal
Description
Contact properties
→
External ID, Tags
HubSpot contact data matches and enriches OneSignal users via External ID and Tags.
Workflows
←
Message Templates
OneSignal Templates are available for selection in HubSpot workflow actions.
The integration does not sync HubSpot lists, deals, or company records to OneSignal automatically. Use workflow actions to explicitly pass the data you need.
What happens if the External ID doesn’t match a OneSignal user?
The Send Notification and Edit Tags actions silently fail. No message is sent and no tags are set. Always place a Create User action before other OneSignal actions in your workflow to ensure the user exists in OneSignal.
Can I use HubSpot lists to target OneSignal segments?
Not directly. HubSpot lists and OneSignal segments are independent systems. To bridge them, create a workflow that enrolls contacts from a HubSpot list and uses the Edit Tags action to set a tag. Then build a OneSignal segment based on that tag. See Promotional campaign via in-app message for a worked example.
Push notifications can be sent using templates or form fields. Email and SMS/RCS can only be sent using Templates created in OneSignal. In-app messages cannot be sent from HubSpot workflows. Use the tag-and-segment pattern instead.
Why didn’t my in-app message display after the tag was set?
Tags alone do not trigger in-app messages. The tag adds the user to a segment, but the in-app message still requires a trigger to display. If the tag is set while the user is actively using the app, the message will not appear until the next session (30+ seconds in background). Set the in-app message trigger to On app open for the most reliable behavior. See In-App Message Triggers for all trigger options.
Can I use HubSpot webhooks to call the OneSignal API directly?
Yes. HubSpot’s Custom Code workflow action lets you make HTTP requests to external APIs. You can call the OneSignal REST API to send messages, create users, or update tags outside the native integration. This is useful for use cases the native actions do not cover, such as sending to a segment rather than an individual user.
Can I send OneSignal message events back to HubSpot?
Yes. Use Event Streams to export OneSignal message events (sent, clicked, etc.) to a webhook endpoint. You can route these events to HubSpot’s Custom Events API or use a middleware service to update HubSpot contact properties based on OneSignal engagement data.
There are two options for getting HubSpot users into a OneSignal Journey:
Tags: Use the Edit Tags action to set a tag on the user. Create a segment in OneSignal based on that tag and use the segment as a Journey entry condition.
Custom Events: Use HubSpot’s Custom Code action to call the OneSignal Custom Events API, which can serve as a Journey entry trigger.
Can I send custom events from HubSpot to OneSignal?
Not through the native workflow actions. The native integration supports Create User, Edit Tags, and Send Notification. To send custom events, use HubSpot’s Custom Code action to call the OneSignal Custom Events API directly.
What HubSpot enrollment triggers work with OneSignal?
Any HubSpot enrollment trigger works. The OneSignal actions are standard workflow actions that execute regardless of how the contact was enrolled. Common triggers include:
Contact property changes (lifecycle stage, lead status, last activity date)
Form submissions (signup forms, demo requests, event registrations)
List membership (added to a static or active list)
