Skip to main content
POST
/
apps
/
{app_id}
/
custom_events
Create Custom Events
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "name": "<string>",
      "external_id": "<string>",
      "onesignal_id": "<string>",
      "timestamp": "<string>",
      "idempotency_key": "<string>",
      "properties": {}
    }
  ]
}
'
{
  "errors": [
    {
      "event_user_id": "abc123",
      "event_id": "567491ee-9105-4a87-9cbc-ed78a571645b",
      "error": {
        "code": "not found",
        "title": "failed to find a onesignal_id for user_id abc123"
      }
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Custom Events API allows you to track user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones. See Custom events for more information.

​
Use Cases

Custom events can be used to:

​
Error handling

If individual events can’t be processed, an errors key will be returned in the response (with HTTP status 202) containing information about each failing event. The most common event-specific error is a failure to find a user associated with the External ID or OneSignal ID in the event. If you’d like to retry sending events in the case of a failure, you only need to re-send the events for which errors were returned — events that don’t have an error associated with them are still processed. However, if a 5xx HTTP response is returned, you must retry the entire batch of events. In either case, if you are implementing retry, make sure to also pass an idempotency_key.

​
Duplicate events

If you implement retry behavior for your custom event delivery, please provide the idempotency_key field. Each unique event should get its own unique UUID, and when retrying delivery for events, the same UUID must be provided. Duplicate events with the same idempotency_key will be ignored on a best-effort basis within a 4-hour period. This allows you to avoid erroneously triggering Journeys multiple times or incurring charges for storing unnecessary duplicate events.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY

Your app API key with prefix Key . See Keys & IDs.

Path Parameters

​
app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Body

application/json
​
events
object[]
required

Array of event objects to be recorded. Maximum size for each event is 2024 bytes. Maximum size of request is 1 MB.

Response

Accepted with optional partial-success details. The response body lists any individual events that could not be processed (typically because the supplied event_user_id does not resolve to a OneSignal user); other events in the same payload were processed normally. An empty errors array (or absent body) means every event was accepted.

​
errors
object[]

Errors for specific events in the payload. If this is returned, only the specified events have failed -- other events in the same payload were successfully processed.