Custom events are currently in Early Access. To request access, contact support@onesignal.com with:
  • Your company name
  • Your OneSignal Organization ID
  • The App ID(s) you want to enable

​
Overview

Custom Events let you track meaningful user actions from your app, website, or external systems — and act on them in real time. They complement OneSignal’s built-in Message Events by letting you send events for behaviors that happen outside of OneSignal and use them to deliver more targeted, relevant, and timely messaging. You can:
  • Send events directly from your app or website using OneSignal SDKs
  • Import events from your integrations, CDP, or data warehouse
  • Use them to trigger Journeys, activate Wait Until steps, and segment users based on real-time behavior (segmentation option coming soon)
Example use cases:
  • User signs up → Start onboarding Journey
  • User abandons checkout → Send reminder or offer
  • Gamer reaches new level → Send in-app reward
  • User tries to cancel account → Trigger winback campaign

​
What is a Custom Event?

A Custom Event is any tracked user action — or inaction — that matters to your business. Common examples include:
  • Making a purchase
  • Completing a game level
  • Starting a workout
  • Cancelling a subscription
Each event can include properties to provide extra context. Custom Event structure:
  • name (string, required) — Event name, max 128 characters
  • properties (object, optional) — Context data in JSON
  • User identifier (required) — Either external_id or onesignal_id
Example: 
{
  "event": "purchase",
  "properties": {
    "item": "T-shirt",
    "size": "small",
    "color": "blue",
    "price": 24.99
  }
}
Custom Events can be:
  • Produced in real time from your app or site (OneSignal Mobile/Web SDKs)
  • Ingested from integrations like Segment, Amplitude, or Databricks (coming soon)
  • Imported from your warehouse or CDP (coming soon)

​
Tags vs Custom Events

Tags and Custom Events are both ways to add data to your users. However, there are some key differences:
FeatureTagsCustom Events
Data usageSegmentation and personalizationTrigger Journeys, Wait Until steps, personalization within Journeys
Data retentionLifetime30+ days (configurable)
Data formatKey-value string pairsJSON
Data sourceOneSignal SDK, API, or integrations (limited)OneSignal SDK, API, or integrations
Data accessSegmentation and message personalizationJourneys and Journey-message-template personalization, Segmentation (Coming soon)
Data availabilityUpdated via API (can be a 15 minute delay)dependent on source, but will be real time with the SDK, API or Segment.com/Amplitude CDP integrations
The key distinction between Tags and Custom Events is in their depth and use cases. Tags provide a simple, flexible way to capture user attributes that can be used for personalization and basic segmentation. Custom Events, while supporting many of the same purposes, allow for richer data capture and enable more advanced segmentation and targeting. In practice, you will likely use both:
  • Tags for user properties that are static and don’t change often
  • Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

​
Getting Custom Events into OneSignal

You can generate events directly or ingest them from another system.
All events — whether generated from an SDK or ingested from a Data Warehouse — are treated the same for billing purposes.

​
OneSignal SDK and API

Send events via: Example: Send via API
curl
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    {
      "name": "completed_onboarding",
      "external_id": "user_12345",
      "properties": {
        "plan": "Pro",
        "time_to_complete": 600
      }
    }
  ]
}'
​
name
string
required
The identifier or name of the event. Maximum 128 characters.
​
external_id
string
required
The external ID of the user targeted for the event. Either the user’s External ID or OneSignal ID is required.
​
properties
object
Optional parameters about the event (e.g., plan name, product ID, price).
This event will immediately add the user with external_id user_12345 to a Journey with completed_onboarding as the custom event entry-rule trigger or wait until action.

​
Integrations

If events are already tracked elsewhere, import them via supported integrations.

​
Viewing and verifying events

After events start flowing in, you can view and troubleshoot them through several tools in OneSignal.

​
Event List Tab

Navigate to your Organization

The Event List tab provides a high-level dashboard of your events, organized by event type. For each event kind, you can see the total number of events ingested, the most recently ingested event (displayed in JSON format with its properties), the source of the event (SDK, API, or integration), and the last time the event type occurred. Within the detail view of each event, you also have the option to update its retention period. The sub-detail view offers additional insights into three key areas:
  • Source Breakdown – Displays the number of events ingested by source, with the option to expand and view the latest schema of the events along with the timestamp of the last event seen.
  • Activities – Lists the 10 most recent events ingested, showing their source and timestamp. Each entry can be expanded to reveal the full JSON payload of the event.
  • Usage – Shows where a particular event is being used within OneSignal, such as in segments or journeys. From here, you can click directly into the relevant segment or journey to access its settings.

​
Event Activity Tab

Navigate to your Organization

The Event Activity tab provides a live feed of the most recent events ingested into your OneSignal app. You can expand the feed to review events from up to 90 days ago and apply filters by source, event properties, or external ID. This tab is especially useful for debugging issues when configuring event sources, as it allows you to validate whether events are reaching your application as expected. Note that the feed does not auto-refresh, so you’ll need to manually refresh it after sending new events to see the latest activity.

​
Event Storage Tab (Coming Soon)

A dedicated view to manage the storage of the events for your OneSignal Application.

​
Using Custom Events in OneSignal

​
Trigger Journeys with events

Event-triggered Journeys let you immediately message users based on real-time activity—no need to wait for segment updates. You can start a Journey the moment a user takes a key action.

​
Wait Until event

Use the Wait Until step to pause users in a Journey until a specific custom event or other action.
You can also define an expiration window. If the user doesn’t meet the condition in time, you can continue down a fallback path, send an alternate message, or exit the Journey.

​
Segmentation by Custom Events (coming soon)

You can create a segment based off of the occurance of a custom event. This will enable you to segment users based off of behavior on your Application uisng the OneSignal SDK or from events captured outside of OneSignal.

​
Plan availability and retention costs

Custom Events are available on all paid plans. Please see the Billing FAQ for more details.