Send message data out of OneSignal in real-time to your chosen destination.
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.
Setting up Event Streams requires collaboration with your technical team. Here are some tips to facilitate the conversation:
By working closely with your technical team, you can unlock the power of event streaming to enhance your growth strategy.
You can configure a new event stream for your OneSignal application under Data > Event Streams.
Events can’t be sent unless the following requirements are met:
Click “Select Events” to select your choice of events to trigger an event stream.
Trigger Webhook
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 Selection
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.
Filtering events by template
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.
Copying the Template ID of a template
Alternatively, you can copy the message/template identifier of what you’re viewing directly from the URL :
https://dashboard.onesignal.com/apps/{APP_ID}/templates/{TEMPLATE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/notifications/{MESSAGE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/email/{MESSAGE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/sms/{MESSAGE_ID}
Select the HTTP method, the URL, and add headers for the event stream. This is where authentication should be configured to ensure secure communication between OneSignal and your systems.
The URI and Headers can contain liquid syntax which will come from both the user properties and properties of the event stream.
You can add authentication headers to validate that requests to your endpoint are genuinely from OneSignal. Common authentication methods include:
Authorization
header, where YOUR_TOKEN
is provided by your system or 3rd party like:
Basic {{YOUR_TOKEN}}
Bearer {{YOUR_TOKEN}}
ApiKey {{YOUR_API_KEY}}
X-API-Key: {{YOUR_API_KEY}}
Note: OneSignal does not provide encryption services
If you are looking for an easy way to test, use webhook.site. Find “Your unique URL” in the center of the page. Copy that URL and use it in the URL field of your event stream configuration.
Configure Webhook
The following headers are restricted and can’t be set.
content-length
referer
metadata-flavor
x-google-metadata-request
host
x-onesignal*
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.
Event Stream Body Options
On the right, you can see an example cURL request built from what has been input during event stream setup
cURL Preview of Event Stream
You can personalize all fields in your Event Stream with predefined Event Streams Data. This data can be added using Liquid Syntax. This gives you the flexibility to use event streams for nearly any use case.
See Event Streams Data for a list of all event, message, and user event data available for personalization.
Select the “Custom Body” in the drop-down:
Custom Body
When using Liquid syntax within JSON, proper quoting depends on the data type:
Guidelines for JSON Formatting
Examples
✅ Correct
❌ Incorrect
✅ Correct
❌ Incorrect
✅ Correct
❌ Incorrect
Best practices for handling multilingual conditionals in liquid syntax
To avoid issues with language-based conditionals
user.language
directly in conditionals, not in variables like userLang
, for better compatibility.content/title/en
for reliability.This approach minimizes parsing errors and ensures compatibility with the system.
For details and options on how to personalize your messages using Liquid syntax, check out our Using Liquid Syntax Guide.
You can see how your event stream performs over a period of time on the event stream report page under the Report 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.
Event Stream Logs and Metrics
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.
OneSignal will send out emails to app admins and org admins when an event stream starts to experience a significant volume of failed events (but has not yet been disabled) as well as an email when the event stream is disabled when too many events have failed to send. There will also be a banner on the event streams index page notifying a OneSignal user of issues with one of their event streams.
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.
Use a tool like https://webhook.site/ and set the Your unique URL provided into the URL parameter in the Event Stream with the POST method.
The URL matches the "Your unique URL" from webhook.site
Set the events you want to track. In this example, we will use the push events, but any will work.
Push message events selected, but any can be used for testing.
In this example, we will use the above Example body.
Save the event and set it live.
Send a message to trigger the event. In webhook.site we will see the event with the following data:
Example using webhook.site
This shows the following:
Send message data out of OneSignal in real-time to your chosen destination.
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.
Setting up Event Streams requires collaboration with your technical team. Here are some tips to facilitate the conversation:
By working closely with your technical team, you can unlock the power of event streaming to enhance your growth strategy.
You can configure a new event stream for your OneSignal application under Data > Event Streams.
Events can’t be sent unless the following requirements are met:
Click “Select Events” to select your choice of events to trigger an event stream.
Trigger Webhook
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 Selection
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.
Filtering events by template
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.
Copying the Template ID of a template
Alternatively, you can copy the message/template identifier of what you’re viewing directly from the URL :
https://dashboard.onesignal.com/apps/{APP_ID}/templates/{TEMPLATE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/notifications/{MESSAGE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/email/{MESSAGE_ID}
https://dashboard.onesignal.com/apps/{APP_ID}/sms/{MESSAGE_ID}
Select the HTTP method, the URL, and add headers for the event stream. This is where authentication should be configured to ensure secure communication between OneSignal and your systems.
The URI and Headers can contain liquid syntax which will come from both the user properties and properties of the event stream.
You can add authentication headers to validate that requests to your endpoint are genuinely from OneSignal. Common authentication methods include:
Authorization
header, where YOUR_TOKEN
is provided by your system or 3rd party like:
Basic {{YOUR_TOKEN}}
Bearer {{YOUR_TOKEN}}
ApiKey {{YOUR_API_KEY}}
X-API-Key: {{YOUR_API_KEY}}
Note: OneSignal does not provide encryption services
If you are looking for an easy way to test, use webhook.site. Find “Your unique URL” in the center of the page. Copy that URL and use it in the URL field of your event stream configuration.
Configure Webhook
The following headers are restricted and can’t be set.
content-length
referer
metadata-flavor
x-google-metadata-request
host
x-onesignal*
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.
Event Stream Body Options
On the right, you can see an example cURL request built from what has been input during event stream setup
cURL Preview of Event Stream
You can personalize all fields in your Event Stream with predefined Event Streams Data. This data can be added using Liquid Syntax. This gives you the flexibility to use event streams for nearly any use case.
See Event Streams Data for a list of all event, message, and user event data available for personalization.
Select the “Custom Body” in the drop-down:
Custom Body
When using Liquid syntax within JSON, proper quoting depends on the data type:
Guidelines for JSON Formatting
Examples
✅ Correct
❌ Incorrect
✅ Correct
❌ Incorrect
✅ Correct
❌ Incorrect
Best practices for handling multilingual conditionals in liquid syntax
To avoid issues with language-based conditionals
user.language
directly in conditionals, not in variables like userLang
, for better compatibility.content/title/en
for reliability.This approach minimizes parsing errors and ensures compatibility with the system.
For details and options on how to personalize your messages using Liquid syntax, check out our Using Liquid Syntax Guide.
You can see how your event stream performs over a period of time on the event stream report page under the Report 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.
Event Stream Logs and Metrics
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.
OneSignal will send out emails to app admins and org admins when an event stream starts to experience a significant volume of failed events (but has not yet been disabled) as well as an email when the event stream is disabled when too many events have failed to send. There will also be a banner on the event streams index page notifying a OneSignal user of issues with one of their event streams.
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.
Use a tool like https://webhook.site/ and set the Your unique URL provided into the URL parameter in the Event Stream with the POST method.
The URL matches the "Your unique URL" from webhook.site
Set the events you want to track. In this example, we will use the push events, but any will work.
Push message events selected, but any can be used for testing.
In this example, we will use the above Example body.
Save the event and set it live.
Send a message to trigger the event. In webhook.site we will see the event with the following data:
Example using webhook.site
This shows the following: