Event Streams allows you to send message data out of OneSignal in real-time to your chosen destination. Event streams are a great way to connect OneSignal to other products within your marketing ecosystem. They enable your team to trigger corresponding messaging, maintain records, and much more.

Common challenges this addresses:

1. 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.
2. 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.
3. 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.

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.

How to partner with your technical team

Setting up Event Streams requires collaboration with your technical team. Here are some tips to facilitate the conversation:

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.

By working closely with your technical team, you can unlock the power of event streaming to enhance your growth strategy.

Requirements

Events can't be sent unless the following requirements are met:

• 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”)

Setup

You can configure a new event stream for your OneSignal application under Data → Event Streams.

Selecting event stream triggers

Click “Select Events” to select your choice of events to trigger an event stream.

The data that may be sent with these events all similar enough that you can send events triggered by multiple channels through the same event stream. Another approach would be to define multiple event streams each for a single channel or event for more granular control or to reduce the scale of data sent.

Event stream filters

You can optionally further refine events by specifying the identifiers of one or more messages or templates, enabling you to receive only events related to specific messages within your app. Refer to the instructions below to enable event stream filtering.

Message and template identifiers can be copied by navigating to Messages > Push, Emal, SMS, or Teamlates, -clicking the action button of the desired message or template, and selecting Copy Message ID or Copy Template ID from the action menu.

Alternatively, you can copy the message/template identifier of what you're viewing directly from the URL :

• 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}

Configuring the event stream

Select the HTTP method, the URL, and add headers for the event stream this is where authentication will often be. The URl and Headers can contain liquid syntax which will come from both the user properties, but also properties of the event stream.

You may add any headers needed, common examples being an Authorization key, with values like Basic {{YOUR_TOKEN}} or Bearer {{YOUR_TOKEN}} where YOUR_TOKEN is provided by your system or 3rd party. OneSignal does not provide encryption services.

Disallowed headers

The following headers are restricted and can't be set.

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

Body

The body for an event stream will be JSON. The body JSON can be defined either as individual key/value pairs or as an editable code block. To change the input method use the first dropdown under the body heading and select the custom body.

On the right, you can see an example cURL request built from what has been input during event stream setup

Personalization

You can personalize all fields in your event stream using information about the user and the message on whose behalf it was triggered. This gives you the flexibility to use event streams for nearly any use case.
​
An event stream event provides access to objects such as event and message each with a specific structure. For example, if you need to embed the user's External ID in your event stream URL, you can use a template like: ​<https://example.com/webhook/user/{{event.external_id}}>. This will dynamically inject the user's External ID into the URL.

📘

Personalizing Messages with Liquid Syntax

For more ways to peronalize your messages usinig Liquid syntax, check out our Using Liquid Syntax Guide.

Event

The event object includes the following properties:

{
  "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.kind": "message.sms.sent",
  "event.id": "ae7eb8b7-5234-475e-886d-966344839600",
  "event.timestamp": "1725412762",
  "event.datetime": "2024-09-04T01:19:22+00:00",
  "event.app_id": "the-onesignal-app-ID",
  "event.subscription_device_type": "SMS",
  "event.subscription_id": "the-subscription-ID",
  "event.onesignal_id": "the-onesignal-ID",
  "event.external_id": "the-users-external-ID"
}

Message

The message object is designed to keep you informed of the messages sent to the end-user. It includes properties like id, template_id, and content which contains the actual text of the message.

{
  "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",  
  "message.name": "the-name-you-set",  
  "message.title": "Claim 50% Off Today",//email subject example
  "message.title": "{'en':'the message title/headings'}", //push title example
  "message.contents": "{'en':'the message content'}",
  "message.template_id": "the-template-uuid-if-set"
}

Check out Message Personalization for more details about how to use liquid templating in general.
Remember that each request represents one message event (if selected for the event stream).

Results & Debugging

You can see how your event stream performs over a period of time on the event stream report page under the 'stats' tab. This will include all-time numbers, the current status of your event stream, and time series data showing what kind of responses the hook has been receiving. Any HTTP response in the 200 range indicates an event was successfully received, while responses in the 400s and 500s indicate errors. A timeout means the server on the other side didn't manage to respond within a reasonable amount of time so OneSignal closed the connection and assumed it failed.

You can see a sampling of recent requests under the 'logs' tab for even more detail. This will show actual requests and the responses from the other side (if applicable). If your event stream has issues, this is a great place to look first. If you need to change/update your event stream, you can edit it on the form page and send test requests to see the full details you need until you can get it right.

Retries / Disabling

When an Event Stream request fails for any recoverable reason (for example, status code 429), OneSignal will retry sending the event again after a short delay. This will happen a few times with increasing delays between requests. If enough retries fail in a row, the hook will be marked as 'failed permanently' and will no longer be retried.

If too many separate requests fail in a row, this is probably because of an issue on the receiving end; the receiving end could have errors or have changed/disabled something. OneSignal will continue to send requests to a certain point, but if the requests continue to fail, the event stream might be disabled by OneSignal. If this happens, make sure to spend some time troubleshooting, fixing and then testing the event stream before re-enabling it.

A poorly performing API could lead to event stream disablement. It is important that the API which ingests an event stream is able to handle the volume of events which is produced by message sends. Reviewing the volume of message sends that are produced by your app will reflect the performance required of your API.

We recommend that the API receiving the event stream record an event without any other online processing. This will keep response times low and prevent any latency related issues. Slow response time or status code 429 responses from your API can cause a backlog of events. A consistent backlog of events will lead OneSignal to disable the event stream so you can update your API to handle the required throughput.

Each Event Stream has a unique event.id for each event. This can be used as a header or in the body of the message as a way to check and potentially deduplicate requests if you see the same ones coming through.

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.