Skip to main content

​
What are Custom Events?

A Custom Event is a named user action (or inaction) that you send to OneSignal. You send events from your app, website, or external systems so you can trigger automation, control Journey flow, and personalize user experiences in real time. Examples include:
  • Completed onboarding
  • Made a purchase
  • Abandoned a cart
  • Canceled a subscription
  • Reached a new game level
When OneSignal receives a Custom Event, you can:
  • Start a Journey
  • Continue a Journey with a Wait Until step
  • Exit users from a Journey
  • Personalize messages using event properties
  • Segment users by behavior (Early Access)

​
When should you use Custom Events?

Use Custom Events when:
  • Messaging should respond to real-time user behavior
  • The data represents something that happened (not permanent state)
  • You need event properties for personalization or Journey logic
Do not use Custom Events when:
  • You want to store long-term user attributes (use Tags instead)
Custom Events represent something that happened at a specific point in time. Unlike Tags, they do not permanently update the user’s profile — they record behavior.See Tags vs Custom Events below for a detailed comparison.

​
Custom Event structure

Custom Events include the following fields:
​
name
string
required
The event name. Maximum 128 characters.
​
properties
object
Optional parameters that describe the event (for example: plan name, product ID, or price). These can be used for personalization and Journey flow control.
​
external_id
string
The user’s External ID. A user identifier is required when using the Create Custom Events API. Either external_id or onesignal_id must be provided.
​
timestamp
string
The time the event occurred (or will occur), formatted as an ISO 8601 string. See Create Custom Events API.
​
idempotency_key
string
A unique UUID used to prevent duplicate event processing. See Create Custom Events API.
Event size limits:
  • Maximum event payload: 2024 bytes
  • Maximum request size (multiple events): 1 MB

​
Send Custom Events to OneSignal

Send Custom Events using the following methods:
All events are treated the same for billing purposes, regardless of source.
Example Custom Event payload:
JSON
{
  "events": [
    {
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "idempotency_key": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

​
Verify events are received

After sending events, confirm they are reaching OneSignal in Data > Custom Events.

​
Event List tab

The Event List tab provides an overview of all Custom Events in your app, organized by event name. For each event type, you can see:
  • Total events ingested
  • Most recent event (with full JSON payload and properties)
  • Event source (SDK, API, or integration)
  • Last occurrence timestamp
Select an event to open its detail view, where you can also update its retention period. The detail view includes:
  • Source Breakdown: Number of events ingested by source. Expand to view the latest event schema and the timestamp of the most recent event.
  • Activities: The 10 most recent events, including source and timestamp. Expand any entry to inspect the full JSON payload.
  • Usage: Where the event is currently used (Journeys or segments). Click directly into the associated Journey or segment to modify its settings.

​
Event Activity tab

The Event Activity tab provides a live feed of the most recent events ingested into your OneSignal app. Use it to:
  • Filter by event name, source, or external ID
  • Inspect full JSON payloads
  • Debug integration issues
The feed does not auto-refresh. Refresh manually after sending new events.

​
Use Custom Events in OneSignal

After events are flowing into OneSignal, you can use them in the following ways:

​
Trigger Journey entry and exit rules

Set a Custom Event as a Journey entry or exit rule to immediately add or remove users when the event occurs. Example:
  • signup_completed → Start onboarding or remove from a trial-encouragement Journey
  • purchase → Send confirmation and cross-sell or remove from abandoned cart Journey

Journey settings

Enter users into Journeys with Custom Events.

​
Control Journey flow (Wait Until)

Use a Wait Until step to hold users until a Custom Event occurs. Example:
  • Wait until purchase after added_to_cart
You can define an expiration window. If the user does not trigger the event in time, you can send a fallback message or exit the Journey.

Journey Wait Until step

Hold users until a Custom Event occurs.

​
Personalize Journeys with event properties

Reference event properties using Liquid in your Journey templates. Example:
Liquid
Thanks for purchasing {{ journey.first_event.properties.item }}!

Custom Event personalization

Complete guide to using event properties to personalize Journeys.

​
Segment users with Custom Events

Create a segment based on the occurrence of a Custom Event.
Custom Event segmentation is in Early Access.To request access, email support@onesignal.com with:
  • Your company name
  • Your OneSignal App ID(s)
Current limitations:
  • Not supported with Email Warm Up or A/B tests
  • Cannot power Journeys
  • Cannot be combined with other segment filters

Segmentation

Complete guide to segmentation.

​
Plan availability and retention costs

Custom Events are available on all paid plans.

Billing FAQ

Learn about event retention and pricing.

​
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 without a Segment, Wait Until steps, personalization directly within Journeys
Data retentionLifetime30+ days (lifetime storage is available)
Data formatKey-value strings or numbersJSON
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)
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