Event Streams

​

Common use cases

1. Customer journey mapping and personalization: stream events to a CRM or Customer Data Platform (CDP) to build comprehensive customer profiles and tailor campaigns across various touchpoints.
2. Analysis and reporting: send message events (e.g., sends, opens, clicks) to a data warehouse to analyze engagement patterns or long-term trends across channels.
3. Compliance and regulatory reporting: stream all message-sent data to a data warehouse for auditing and compliance purposes.
4. AI and predictive models: send message event data to in-house AI or predictive models to create comprehensive customer cohorts and understand churn risks—such as email unsubscribes or message dismissals, which may indicate potential churn.
5. Marketing automation: send engagement events (like message opens or clicks) to other tools to automatically trigger the next steps in the user journey or update customer profiles and recent activity.
6. Data fragmentation: valuable customer data often resides in separate tools (such as customer engagement platforms, CRMs, analytics tools, and data warehouses). Event streaming helps centralize this data, increasing visibility into valuable first-party data and allowing for faster revenue outcomes.
7. Slow communication between systems: by sending live engagement events to other systems, you can trigger actions immediately after an event occurs, rather than waiting hours or days for batched updates. This eliminates reliance on manual imports or data syncs.
8. Spend bloat and technical debt: instead of managing multiple intermediary tools, you can directly connect OneSignal with your data warehouse. This reduces the costly overhead of managing multiple integrations or custom data pipelines, lessens technical debt, and preserves valuable technical resources for product and marketing.

​

How to partner with your technical team

1. Explain the benefits: share your strategy for using this data and how it can enhance marketing campaigns, personalize user experiences, consolidate data, and reduce technical debt.
2. Define the scope: identify where you want the data to be sent, which events you want to track, and the estimated data volume. This will aid in configuring the proper endpoint setup.
3. Provide technical documentation: share OneSignal’s technical documentation and setup instructions. Your development team will need to configure the recipient endpoints and the event stream in OneSignal, ensuring data is routed correctly.
4. Discuss data volume and management: confirm that your systems can handle real-time data flows. It’s recommended that the API handler records events without additional online processing to maintain low response times.
5. Test and troubleshoot: conduct tests to ensure everything is functioning smoothly before going live.

​

Setup

​

Requirements

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

​

Event Selection

Trigger Webhook

Event Selection

​

Event stream filters

Filtering events by template

Copying the Template ID of a template

• Template – https://dashboard.onesignal.com/apps/{APP_ID}/templates/{TEMPLATE_ID}
• Push – https://dashboard.onesignal.com/apps/{APP_ID}/notifications/{MESSAGE_ID}
• Email – https://dashboard.onesignal.com/apps/{APP_ID}/email/{MESSAGE_ID}
• SMS – https://dashboard.onesignal.com/apps/{APP_ID}/sms/{MESSAGE_ID}

​

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

Configure Webhook

​

Disallowed headers

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

​

Body

Event Stream Body Options

cURL Preview of Event Stream

​

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 }}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "template_id": "{{ message.template_id }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}

Custom Body

​

Using Liquid Syntax in JSON

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

​

Strings

// Wrap string values in quotes
{
  "user_id": "{{ user.onesignal_id }}"
}

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

​

Numbers & Booleans

// Don't wrap numbers or booleans in quotes
{
  "user_score": {{ user.tags.score }}
}

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

​

Objects

// Don't wrap objects in quotes.
{
  "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

Event Stream Logs and Metrics

​

Retries / Disabling

​

Tips for Success

1. You typically will want to have event streams connect to your own servers, not third party services.
   1. While there is nothing wrong with connecting directly to a third party the following can be harder to manage: It will be more challenging to configure/debug
   2. The volume of requests will not be managed in OneSignal.
      1. Event stream events will be sent out as fast as users hit the steps in your journey and this might overwhelm other services, hit rate limits, or run up YOUR bill unexpectedly. This is especially common when trying to use another messaging channel for something like SMS. The flexibility of event streams means OneSignal does not know what you’re trying to accomplish with them, so you may want to create a simple service of your own that accepts the event stream requests and then correctly handles your third-party connection limits, rate limits, and queue.
2. Many services have public HTTP APIs which means you can connect to them with an event stream; look for their API docs and examples of how to make an HTTP request to find the right place to get started.

​

Testing

The URL matches the "Your unique URL" from webhook.site

Push message events selected, but any can be used for testing.

Example using webhook.site

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