OneSignal Databricks integration

OneSignal Databricks integration overview

​
Overview

The OneSignal + Databricks integration enables automatic export of message event data from OneSignal to your Databricks lakehouse. This removes the need for manual data handling and provides near real-time access to user engagement data for custom analytics, dashboards, and cross-functional reporting.

You’ll gain insight into user interactions across email, push notifications, in-app messages, and SMS. Currently, the integration supports message send and engagement events, with more event types planned for future updates.

​
Requirements

​
OneSignal

​
Databricks

  • Platform: AWS, Azure, or GCP
  • Plan: Premium or higher
  • Unity Catalog: Required (legacy deployments not supported)
  • SQL Warehouse: Required for ingestion and querying

​
Setup

​
Collect SQL warehouse details

1

Log in to your Databricks workspace

Go to SQL Warehouses in your Databricks workspace.

2

Select your warehouse

Select your warehouse and open the Connection details tab.

3

Save the following details

  • Server Hostname
  • Port
  • HTTP Path
Databricks SQL connection details for Fivetran setup

Databricks SQL connection details for Fivetran setup

​
Create a service principal

1

Go to the Service Principals page

Go to Workspace Settings > Identity and Access > Service Principals.

2

Add a new service principal

Click Add Service Principal, then Add New.

3

Name the service principal

Name it (e.g., onesignal-sync).

Modal for adding a service principal, with the 'Add new' option highlighted

Modal for adding a service principal, with the 'Add new' option highlighted

​
Generate a secret

1

Click into the created principal

2

Go to the Secrets tab

3

Generate a secret

Click Generate Secret and save it securely.

The secret is only visible once—store it safely.

Databricks 'Generate secret' modal showing OAuth secret and client ID for API authentication

Databricks 'Generate secret' modal showing OAuth secret and client ID for API authentication

​
Assign permissions

1

Navigate to your Catalog and open the Permissions tab

2

Click Grant

3

Assign the following permissions to the service principal

  • USE CATALOG
  • USE SCHEMA
  • SELECT
  • MODIFY
  • CREATE SCHEMA
  • CREATE TABLE
Privilege assignment screen for a Databricks principal with custom catalog permissions selected

Privilege assignment screen for a Databricks principal with custom catalog permissions selected.

​
Connect OneSignal

1

Activate the integration

In OneSignal, navigate to Data > Integrations > Databricks.

2

Enter the details

  • Server Hostname
  • Port
  • HTTP Path
  • Catalog Name
  • Schema Name
  • Service Principal credentials (ID + Secret)
OneSignal Databricks Configuration form with fields for catalog, hostname, HTTP path, and OAuth credentials

OneSignal Databricks Configuration form with fields for catalog, hostname, HTTP path, and OAuth credentials.

3

Configure the integration

  • Sync Frequency: as often as every 15 minutes
  • Dataset/Table Names: pre-set as onesignal_events_<app-id> and message_events (editable)
  • Event Types: choose which to sync—select all or just what you need
4

Select events

Select the events you care to receive in your Databricks catalog.

OneSignal event export settings screen showing sync status, dataset configuration, and selected message event types

OneSignal event export settings screen showing sync status, dataset configuration, and selected message event types.

5

Complete the setup

Click Save and wait for the success confirmation

​
Generate message events

Send messages via push, email, in-app, or SMS to trigger events that will sync based on your Integration Settings. You can update which events to sync within your OneSignal dashboard Data > Integrations > Databricks.

​
View data in Databricks

  1. Open your Catalog in Databricks.

  2. Once syncing completes, your configured schema will appear.

  3. Access and query the message_events table.

    Databricks Catalog view showing OneSignal message events table under a production schema

    Databricks Catalog view showing OneSignal message events table under a production schema.

  4. Click into tables for sample data preview.

    Sample data from the message_events_1 table with synced OneSignal event fields

    Sample data from the message_events_1 table with synced OneSignal event fields.

If you run into issues like missing schemas, permission errors, or malformed events, contact support@onesignal.com.

​
Events and properties

​
Message event kinds

Property: event_kind Type: String

The kind of message and event (e.g. message.push.received, message.push.sent).

Message Event (OneSignal)event_kindDescription
Push Sentmessage.push.sentPush notification successfully sent.
Push Receivedmessage.push.receivedDelivered push (see Confirmed Delivery).
Push Clickedmessage.push.clickedUser clicked the push.
Push Failedmessage.push.failedDelivery failure. See message reports.
Push Unsubscribedmessage.push.unsubscribedUser unsubscribed from push.
In-App Impressionmessage.iam.displayedIn-App message shown.
In-App Clickedmessage.iam.clickedIn-App message clicked.
In-App Page Viewedmessage.iam.pagedisplayedIn-App page shown.
Email Sentmessage.email.sentEmail delivered.
Email Receivedmessage.email.receivedEmail accepted by recipient’s mail server.
Email Openedmessage.email.openedEmail opened. See Email Reports.
Email Link Clickedmessage.email.clickedLink in email clicked.
Email Unsubscribedmessage.email.unsubscribedRecipient unsubscribed.
Email Marked Spammessage.email.resporedasspamMarked as spam. See Email Deliverability.
Email Bouncedmessage.email.hardbouncedBounce due to permanent delivery failure.
Email Failedmessage.email.failedDelivery failed.
Email Suppressedmessage.email.supressedSuppressed due to suppression list.
SMS Sentmessage.sms.sentSMS sent.
SMS Deliveredmessage.sms.deliveredSMS successfully delivered.
SMS Failedmessage.sms.failedSMS failed to deliver.
SMS Undeliveredmessage.sms.undeliveredSMS rejected or unreachable.

​
Event data schema

For each message event generated by a user, the following metadata will be attached to the record.

Column NameTypeDescription
event_idUUIDUnique identifier for the event
event_timestampTimestampTime of event occurrence
event_kindStringThe Event Kind
subscription_device_typeStringDevice type (e.g., iOS, Android, Web, Email, SMS)
languageStringSubscription language code
versionStringIntegration version
device_osStringDevice operating system version
device_typeNumberNumeric device type
tokenStringPush token, phone number, or email
subscription_idUUIDSubscription ID
subscribedBooleanSubscription status
onesignal_idUUIDOneSignal user ID
last_activeStringLast active timestamp
sdkStringOneSignal SDK version
external_idStringExternal user ID that should match the integration user ID
app_idUUIDApp ID from OneSignal
template_idUUIDTemplate ID (if applicable)
message_idUUIDMessage batch/request ID
message_nameStringName of the message
message_titleStringMessage title (English only)
message_contentsStringTruncated message body (English only)
_created, _id, _index, _fivetran_syncedInternal useFivetran sync metadata

​
Notes

  • Syncs after saving/activating may take an additional 15-30 minutes to complete.
  • Deactivating may still result in one final sync after deactivation.
  • To ensure efficient data synchronization, our system automatically creates and manages staging datasets. These datasets, named with a pattern like fivetran_{two random words}_staging, temporarily store data during processing before it’s integrated into your main schema. These staging datasets are essential for maintaining a streamlined workflow and should not be deleted, as they will be automatically recreated.

​
FAQ

​
Why do I see different message IDs with the same content?

This happens when the same message is sent more than once, likely via a transactional flow or message template reused across multiple sends.