OneSignal

The OneSignal integration forwards Rovenue revenue events (purchases, trial conversions, renewals, refunds, cancellations) and subscription-lifecycle events (trials, grace period, billing issues, plan changes) as OneSignal custom events, via OneSignal's custom_events REST endpoint — so you can enter subscribers into Journeys, drive Wait Until steps, and personalize messages based on their Rovenue purchase and subscription history.

OneSignal is a push/messaging platform, not an analytics warehouse: this integration sends events, not a full profile sync. It does not push user properties/tags, and it does not read anything back from OneSignal.

Chosen surface: the Custom Events API

OneSignal offers two ways a server could push subscription data into a user's timeline: a contemporary Custom Events API (POST /apps/{app_id}/custom_events), or the older Tags (user-properties) update. This integration uses the Custom Events API — it is documented, generally available on api.onesignal.com, and is purpose-built for exactly this ("track user behavior... to trigger Journeys, control flow with Wait Until steps, personalize messages, and measure conversions"), unlike Tags, which model static key/value properties rather than a stream of timestamped events. The fallback (Tags) is not used.

Authentication uses OneSignal's modern per-app REST API key with the Key prefix:

Authorization: Key YOUR_REST_API_KEY

1. Get your credentials from OneSignal

1. In the OneSignal dashboard, open your app, then Settings → Keys & IDs.
2. Copy the OneSignal App ID (a UUID).
3. Copy the app's REST API Key.

2. Add the integration in Rovenue

1. In the Rovenue dashboard, navigate to Apps (left sidebar).
2. Find OneSignal under CRM & lifecycle and click it.
3. The side drawer opens. Fill in the Credentials step:
   • App ID — paste the App ID from step 1.
   • REST API key — paste the key from step 1.
4. Click Validate. This sends a real, read-only GET /apps/{app_id} request — it does not write anything and is not counted or billed, unlike some other providers' credential probes.
5. Choose which events to forward, optionally override the default mapping, then activate.

3. Event mapping

Every forwarded key becomes a OneSignal custom event, named per the mapping table below (override any name in the drawer's mapping step):

Every forwarded event carries a payload with rovenue_event (the original Rovenue event key) and outbox_event_id, so you can always trace a OneSignal custom event back to its Rovenue source. revenue.* events also carry product_id when known.

Amount/currency are included only when both are present and valid. Unlike a structured purchase record, OneSignal's custom-events payload has no required monetary schema — so when a revenue event has an amount but the subscriber's currency isn't known, Rovenue never guesses a currency (it does not default to "USD"). In that case the event is still forwarded (it's still useful for triggering a Journey), just without the amount/currency fields.

4. Identity resolution — $onesignalId is required

Every custom event needs a OneSignal user id. Rovenue requires the reserved subscriber attribute $onesignalId — OneSignal's own internal user id (OneSignal ID), obtained from the OneSignal SDK once a device is registered (e.g. OneSignal.User.onesignalId in the current SDKs' User Model). Set it on the subscriber via setAttributes alongside your other reserved identity attributes.

If $onesignalId is not set on a subscriber, every event for that subscriber is skipped with reason no_user_data (visible in the connection's Delivery Log) — there is no fallback to a Rovenue-internal id, since Rovenue has no way to derive OneSignal's own user id from anything else it holds.

See Subscriber Identity Attributes for the full reserved-attribute reference, including $onesignalId.

5. Verify events are arriving

1. Open Apps → OneSignal → Delivery Log in the Rovenue dashboard and check for succeeded rows with HTTP 200/202.
2. In OneSignal, look up the user by their OneSignal ID and check their timeline / any Journey configured with a Custom Event trigger for the mapped names above.
3. If events are not appearing:
   • A 401/403 response means the REST API key is wrong or doesn't belong to the configured App ID.
   • A 400 response usually means a malformed request — check the Delivery Log's response body.
   • A 429 response includes a Retry-After; Rovenue retries these automatically.
   • Confirm the subscriber has $onesignalId set (missing it skips silently with no_user_data).
   • Ensure the event type you're sending is included in the connection's enabled events.