Custom events - OneSignal

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 capture and act on user activity from your app, website, or connected systems.
They allow you to track behaviors that happen outside of OneSignal’s built-in Message Events and use that data to deliver more targeted, relevant, and timely messaging. You can send events directly from your code using the OneSignal SDKs, or ingest them from integrations and data warehouses.
Once the events are in OneSignal, you can use them to trigger Journeys, Wait Until step activation and segment users based on events based on real user behavior. This allows you to send timely, relevant messages in response to key user actions. Example use cases:

A user signs up for your app → Start an onboarding Journey
A user enters checkout but doesn’t complete it → Re-engage with a reminder or offer
A gamer reaches a new level → Send an in-app reward or upsell
A user tries to cancel their account → Start a winback Journey

What is a custom Event?

A Custom Event represents something meaningful that a user does — or doesn’t do — in your product.
Examples include making a purchase, completing a level in a game, starting a workout, or canceling a subscription. Each event can also include properties that add more context. More explictly, a custom event is composed of:

A name to identify the event in string format
An optional payload or properties in JSON format
The user’s alias that performed the event (External ID or OneSignal ID)

For example:

{
  "event": "purchase",
  "properties": {
    "item": "T-shirt",
    "size": "small",
    "color": "blue",
    "price": 24.99
  }
}


---
## Custom Events Can Be

- **Produced** by your app or website using OneSignal's Mobile or Web SDKs.
- **Ingested** from other platforms where the events already exist (e.g., Segment, Amplitude, Databricks).
- **Imported** from your data warehouse or customer data platform.

Once stored in OneSignal, they can power real-time automations, targeted campaigns, and user analytics.

---

## Getting Custom Events Into OneSignal

There are two main ways to add events to OneSignal: **generating them directly** or **ingesting them from another system**.

### Generate Events in Your App

Send events programmatically using:
- **Mobile SDKs:** iOS and Android
- **Web SDK**
- **[Create Custom Events API](https://documentation.onesignal.com/docs/custom-events#generate-custom-events)**

### Ingest Existing Events

If you already track events elsewhere, you can import them via our integrations.

---

### Generate custom events

#### Produce a custom event via OneSignal's SDK

Documentation for our [mobile](https://documentation.onesignal.com/docs/mobile-sdk-reference#custom-events) and [web](https://documentation.onesignal.com/docs/web-sdk-reference#custom-events) SDKs are linked. We aim to support our additional wrapper and server SDKs for custom events in 2026. 

#### Send a custom event via API

You can generate custom events using OneSignal's SDKs. Documentation can be found  

Use the [Create Custom Events API](/reference/create-custom-events) to send a custom event tied to a specific user.

```bash curl
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/integrations/custom_events \
  --header 'Content-Type: application/json' \
  --data '{
  "events": [
    {
      "name": "completed_onboarding",
      "external_id": "user_12345",
      "payload": {
        "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.

payload

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.

Ingesting custom events

Mobile SDKs

Track custom events via our mobile SDKs.

Web SDK

Track custom events via our web SDK.

Create Custom Events API

Create a custom event via our REST API.

Integrations

Track custom events via our integrations.

Coming Soon:

Additional integrations including Appsflyer, RevenueCat and more.

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

Supported integrations for custom events

You can send custom events to OneSignal using the API or via the following integrations. See our integrations page for more details.

Adobe Audience Manager

AlloyDB

Amazon Athena

Amazon Redshift

Amazon S3

Amplitude

Apache Kafka

Azure Synapse

ClickHouse

Confluent Cloud

Databricks

Elasticsearch

Google BigQuery

Google Cloud SQL for PostgreSQL

Google Sheets

Greenplum

Materialize

Microsoft Fabric

Mixpanel

MotherDuck

MySQL

Postgres

Pub/Sub

SingleStore

Snowflake

SQL Server

Starburst Enterprise

Starburst Galaxy

Trino

Twilio Segment

Viewing and Verifying Events

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

Event Index

A high-level dashboard of your events that shows:

The total number of events ingested
Most recently ingested events
The source (SDK, API, integration)
The last time each event type occurred

Activity Feed

Displays your most recent events (up to the past 30 days) in real time.
Refresh the page to see new events as they arrive.

User Profile Event History

View all Custom Events — along with Message Events and other OneSignal activity — for a specific user.
Learn more about the User Profile →

Event Utilization (Coming Soon)

A dedicated view to see where your events are being used in Journeys, Segments, and other features.

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 Node

Use the Wait Until Action feature in Journeys to hold users until they meet a condition such as:

Being added to a segment
Triggering a custom event (e.g., completed onboarding, made a purchase)

This makes your Journeys smarter and more responsive to real behavior—not just elapsed time.

Why use it

Here are a few examples of how you can use Wait Until:

Onboarding: Wait until a user completes setup before showing advanced tips
Promotions: Wait until a user adds a product to cart before sending a discount
(Coming Soon): Only continue for users who clicked a prior message

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.

Event-triggered Journeys

Trigger Journeys using custom events.

Wait Until Action

Let a user sitting in a Journey “wait until” node continue.

Plan Availability and Retention

Custom Events are available on paid plans today. A version for Free plans will be introduced in the future.

Plan	Stored Events / Month	Default Retention	Retention Customization
Growth	1M	30 days	No
Pro	5M	60 days	Yes
Enterprise	10M	90 days	Yes

Retention details:

Measured per event type
Pro and Enterprise can set custom retention periods per event
You are billed based on stored events at the end of each billing cycle
Deleting events or shortening retention reduces billable storage

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​Overview

​What is a custom Event?

​Ingesting custom events

Mobile SDKs

Web SDK

Create Custom Events API

Integrations

​Supported integrations for custom events

Adobe Audience Manager

AlloyDB

Amazon Athena

Amazon Redshift

Amazon S3

Amplitude

Apache Kafka

Azure Synapse

ClickHouse

Confluent Cloud

Databricks

Elasticsearch

Google BigQuery

Google Cloud SQL for PostgreSQL

Google Sheets

Greenplum

Materialize

Microsoft Fabric

Mixpanel

MotherDuck

MySQL

Postgres

Pub/Sub

SingleStore

Snowflake

SQL Server

Starburst Enterprise

Starburst Galaxy

Trino

Twilio Segment

​Viewing and Verifying Events

​Event Index

​Activity Feed

​User Profile Event History

​Event Utilization (Coming Soon)

​Using Custom Events in OneSignal

​Trigger Journeys with events

​Wait Until Node

​Why use it

Event-triggered Journeys

Wait Until Action

​Plan Availability and Retention

Overview

What is a custom Event?

Ingesting custom events

Supported integrations for custom events

Viewing and Verifying Events

Event Index

Activity Feed

User Profile Event History

Event Utilization (Coming Soon)

Using Custom Events in OneSignal

Trigger Journeys with events

Wait Until Node

Why use it

Plan Availability and Retention