OneSignal Webhook Setup Guide

The Native Webhook URL is generated once an account has been linked. You will paste it into OneSignal in a later step.

• Open the linked account in StackOne.
• Copy the value from Native Webhook URL.

Open the OneSignal dashboard and sign in with the account whose API key you connected to StackOne. Enter your Email and Password on the Log in to Your Account screen, then click Log in with Email.

Select the app you connected to StackOne, then click Event streams under Data in the sidebar. Click New Event Stream in the top right.

• The page lists existing streams by Name, Status, Created, Last activated and Destination URL, with All, Active, Inactive and Disabled tabs above them.

Type a name you will recognise later into Event Stream Name, for example StackOne. Under Event Selection, click Select Events.

• Free plans allow one active Event Stream. If you already have one, OneSignal shows You’ve reached the limit of 1 active Event Streams and you must set the existing stream inactive or upgrade before activating another.

The Select an event dialog groups every event by channel — In-App Message, Push Notification, Email, SMS and Live Activity — and shows each event’s payload name beneath it. Tick the events you want delivered, then click Done.

• Select All ticks every event your plan allows; Clear All empties the selection.
• Events your plan cannot receive are greyed out with a padlock.
• Each event counts toward your plan’s message-event volume. A single send to 100,000 users produces 100,000 delivery events on its own, so select only what you need.
• Apply Filters on the previous screen narrows a stream to specific messages or templates instead of all traffic.

Under Configure, leave Method on POST and paste your Native Webhook URL into URL. Under Headers, enter Content-Type as the Key and application/json as the Value.

• The Content-Type header is required. OneSignal sends no content type of its own, and without it StackOne cannot parse the body — every delivery fails with a 500.
• No authentication header is needed. StackOne authenticates the delivery using the token already in the Native Webhook URL.
• Add Header adds further rows if you need them.

Under Body, set the dropdown to Custom Body and paste this template exactly. OneSignal fills the Liquid placeholders in at delivery time, and these key names are what the connector’s event routing reads.

• Paste it as written. The keys are flat and underscored on purpose — OneSignal’s documentation shows a form with dotted keys like "event.kind", which cannot be routed.
• Adding extra fields is safe. Removing event_kind, message_id or event_timestamp is not — routing, record ids and event times come from those three.
• {
    "event_id": "{{ event.id }}",
    "event_kind": "{{ event.kind }}",
    "event_timestamp": "{{ event.timestamp }}",
    "onesignal_id": "{{ event.onesignal_id }}",
    "external_id": "{{ event.external_id }}",
    "app_id": "{{ event.app_id }}",
    "subscription_id": "{{ event.subscription_id }}",
    "message_id": "{{ message.id }}"
  }
  

Click Send Test to post a sample request, then Save to keep the configuration and Activate to start delivering live events.

The Report tab shows Successful, Failed Permanently and Total Sent for all time, alongside an Errors panel counting 4xx Responses, 5xx Responses and Timeouts. The Actions menu in the top right holds the stream’s own controls.

• A run of 5xx Responses with no 4xx Responses usually means StackOne could not read the body — check that the Content-Type header is set.

The Logs tab lists recent deliveries under Success and Failures, each with the response status and timestamp. Expand an entry to see the full request body, the headers OneSignal sent, and the response your endpoint returned.

• This is the fastest way to confirm what OneSignal actually sent — including whether the Content-Type header reached StackOne.
• A delivery that fails repeatedly is retried with increasing delays and then marked permanently failed. Sustained failures disable the whole stream, and admins are emailed before that happens.

Events covering push notification delivery and interaction.

• Push Delivered (message.push.sent) — Fired when a push notification is successfully delivered to the push service (FCM or APNs).
• Push Confirmed Receipt (message.push.received) — Fired when a push notification is received on the device. Needs Confirmed receipt, which requires a paid plan, the OneSignal SDK on the device and a supported platform.
• Push Clicked (message.push.clicked) — Fired when a user taps the push notification to open the app.
• Push Failed (message.push.failed) — Fired when a push fails to be sent.
• Push Unsubscribed (message.push.unsubscribed) — Fired for subscriptions that did not receive the notification because the app was uninstalled, browser data was cleared, or the user opted out. This is a reachability state detected at send time, not an opt-out triggered by this message.

Events covering in-app messages shown inside your app.

• In-App Impression (message.iam.impression) — Fired when an in-app message is successfully displayed on the device.
• In-App Clicked (message.iam.clicked) — Fired when a user taps an element on an in-app message.
• In-App Card Displayed (message.iam.page_displayed) — Fired when an in-app message page is displayed. Useful for tracking carousels.

Events covering email delivery, engagement and deliverability.

• Email Delivered (message.email.received) — Fired when an email is received by the recipient.
• Email Opened (message.email.opened) — Fired when an email is opened by the recipient.
• Email Link Clicked (message.email.clicked) — Fired when a user taps a link in the email.
• Email Unsubscribed (message.email.unsubscribed) — Fired when a user unsubscribes via the unsubscribe link.
• Email Reported as Spam (message.email.reported_as_spam) — Fired when a user reports the email as spam. Gmail requires Google Postmaster Tools to track this.
• Email Bounced (message.email.bounced) — Fired when an email is returned to sender due to a permanent error.
• Email Failed (message.email.failed) — Fired when an email could not be delivered.
• Email Suppressed (message.email.suppressed) — Fired when an email could not be sent because the address is on the suppression list.

Events covering SMS delivery.

• SMS Delivered (message.sms.delivered) — Fired when an SMS is successfully delivered.
• SMS Failed (message.sms.failed) — Fired when an SMS fails to send.
• SMS Undelivered (message.sms.undelivered) — Fired when an SMS could not be delivered.

Events covering iOS Live Activities.

• Live Activity Delivered (message.live_activity.sent) — Fired when a Live Activity is successfully sent to APNs.
• Live Activity Confirmed Receipt (message.live_activity.delivered) — Fired when a Live Activity is received by the recipient.
• Live Activity Clicked (message.live_activity.clicked) — Fired when a Live Activity is clicked by the user.
• Live Activity Failed (message.live_activity.failed) — Fired when a Live Activity fails to send.
• Live Activity Unsubscribed (message.live_activity.unsubscribed) — Fired when a user unsubscribes from Live Activities.