Custom events

Use custom events to drive more engagement with your messaging.

Custom events are currently in Early Access. To request access, contact [e-mail] with:

• Your company name
• Your OneSignal 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. Send user 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:

Feature	Tags	Custom Events
Data usage	Segmentation and personalization	Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys
Data retention	Lifetime	30+ days (lifetime storage is available)
Data format	Key-value strings or numbers	JSON
Data source	OneSignal SDK, API, or integrations (limited)	OneSignal SDK, API, or integrations
Data access	Segmentation and message personalization	Journeys and Journey-message-template personalization, Segmentation (Coming soon)

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

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 with our APIs or ingest them from other systems.

All events — whether generated from an SDK or ingested from a Data Warehouse — are treated the same for billing purposes.

OneSignal API and SDKs

Send events via:

• Create Custom Events API
• Mobile SDKs
• Web SDK

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

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.

---