Event Streams

• Push message events (sent, received, clicked, failed, unsubscribed)
• Email events (sent, opened, clicked, bounced, unsubscribed, etc.)
• SMS events (sent, failed, unsubscribed, etc.)
• In-app message events (impression, clicked, etc.)
• Live Activity events (sent, delivered, confirmed delivery, failed, unsubscribed, clicked)

​

Common use cases

• Centralize engagement data — Stream events to a CRM, CDP, or data warehouse so cross-channel activity (opens, clicks, bounces) lives in one place instead of across disconnected tools.
• Analytics, reporting, and compliance — Land every message event in a warehouse for trend analysis, auditing, or regulatory record-keeping.
• Monitor disengagement — Track unsubscribes, bounces, and dismissals in your own systems to spot retention risks early.
• Trigger external workflows — Fire automations in other tools when a user opens or clicks a message (e.g., update a lead score, start a follow-up sequence).
• Replace batch syncs and extra integrations — React to events in real-time and connect OneSignal directly to your destination, cutting intermediary tools and maintenance cost.

​

Getting your technical team started

1. Decide on a destination and scope — Agree on where events should land (your own API, a data warehouse, a CDP, etc.), which event types to stream (push, email, SMS, IAM, Live Activity), and an estimate of message volume so the endpoint is sized appropriately.
2. Set up an HTTP endpoint — Build or configure a publicly reachable endpoint that accepts POST requests. It should record events quickly without heavy processing to keep response times low. See Retries / Disabling for performance expectations and what happens when the endpoint falls behind.
3. Configure the Event Stream in OneSignal — In Data > Event Streams, select events, set the URL and authentication headers, and define the JSON body using Event Streams Data fields with Liquid syntax.
4. Test end-to-end — Use webhook.site to verify the payload shape and headers before switching to your production endpoint (see Testing).

​

Setup

• A valid URL or IP address for a publicly reachable HTTP(S) endpoint
• URLs and IP addresses must be publicly routable
• Domains must include a recognized top-level domain (e.g., “.com”, “.net”)

​

Event Selection

​

Event stream filters

​

Configure the Event Stream

​

Authentication Headers

• Authorization Header: Add an Authorization header, where YOUR_TOKEN is provided by your system or 3rd party like:
  • Basic {{YOUR_TOKEN}}
  • Bearer {{YOUR_TOKEN}}
  • ApiKey {{YOUR_API_KEY}}
• Custom Headers: You can also add custom headers like:
  • X-API-Key: {{YOUR_API_KEY}}

​

Testing Your Configuration

​

Disallowed headers

• content-length
• referer
• metadata-flavor
• x-google-metadata-request
• host
• x-onesignal*

​

Body

​

Personalization

​

Example body

{
  "Event Data": {
    "event.kind": "{{ event.kind }}",
    "event.id": "{{ event.id }}",
    "event.timestamp": "{{ event.timestamp }}",
    "event.datetime": "{{ event.datetime }}",
    "event.app_id": "{{ event.app_id }}",
    "event.subscription_device_type": "{{ event.subscription_device_type }}",
    "event.subscription_id": "{{ event.subscription_id }}",
    "event.onesignal_id": "{{ event.onesignal_id }}",
    "event.external_id": "{{ event.external_id }}",
    "event.data.page_name": "{{ event.data.page_name}}",
    "event.data.page_id": "{{ event.data.page_id}}",
    "event.data.target_name": "{{ event.data.target_name}}",
    "event.data.target_id": "{{ event.data.target_id}}",
    "event.data.failure_reason": "{{ event.data.failure_reason}}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}

​

Using Liquid Syntax in JSON

• Strings → Must wrap in quotes.
• Numbers → Don’t wrap in quotes.
• Objects → Must not be wrapped in quotes.

{
  "user_id": "{{ user.onesignal_id }}"
}

{
  "user_id": {{ user.onesignal_id }}
}

{
  "user_score": {{ user.tags.score }}
}

{
  "user_score": "{{ user.tags.score }}"
}

{
  "user_data": {{ user.tags }}
}

{
  "user_data": "{{ user.tags }}"
}

1. Use Direct Language Checks: Always check user.language directly in conditionals, not in variables like userLang, for better compatibility.
2. Start Simple: Begin with basic phrases, then gradually add complexity.
3. Avoid Over-Nesting: Keep conditionals flat to prevent parsing issues.
4. Test Basic Punctuation First: Start with simple sentences and punctuation before using special characters.
5. Use Fallbacks: Ensure a default language (e.g., English) in case of missing translations.
6. Stick to Standard Keys: Use standard OneSignal keys like content/title/en for reliability.

​

Results & Debugging

​

Retries / Disabling

1. App and org admins receive an email when failure volume becomes significant (before disabling) and again when the stream is disabled.
2. A banner also appears on the Event Streams index page in the dashboard.
3. Fix the underlying issue, test with the Logs tab or webhook.site, and re-enable the stream.

• Record events quickly — Write the incoming event to a queue or data store without heavy inline processing.
• Avoid slow responses and 429s — Consistent slow response times or rate-limit responses cause events to back up, which leads OneSignal to disable the stream.
• Size for your send volume — If you send 100k messages, expect up to 100k events per selected event type. Review your plan’s message volume and provision accordingly.

​

Tips for Success

• Point streams at your own servers first. You can connect directly to a third-party API, but debugging, rate-limit handling, and volume management are harder when you don’t control the receiving end.
• Buffer before forwarding to third parties. OneSignal sends events as fast as users trigger them — a large send can produce a burst that overwhelms external rate limits or runs up costs (especially with SMS providers). Build a lightweight service that accepts events, queues them, and forwards to external APIs at a pace you control.
• Check third-party API docs. Many services expose public HTTP APIs you can target with an event stream. Look for their docs on authentication, accepted payload format, and rate limits before configuring your stream.

​

Message event data limitations

​

Testing

• Host: the IP address where the request came from. See REST API overview for a list of possible IPs.
• Request Content: the data sent in the body of the event stream.