Custom events are currently in beta. 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 trigger Journeys and Wait Until step activation 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
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)

​
Generate custom events

Depending on your use cases, users can perform events that you detect within your app, on your backend, or in a 3rd party service. OneSignal provides ways to track these events no matter where they are generated via our SDKs, API, or integrations.

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.

​
Example: Send a custom event via API

Use the Create Custom Events API to send a custom event tied to a specific user.
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.

​
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.

​
What you can wait for

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.

​
Supported integrations

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