OneSignal

OneSignal is a multi-channel messaging platform for push notifications, in-app messages, email, and SMS, popular for high-volume consumer apps and web.

Why route OneSignal through Datafly Signal

• Profiles are updated from the server, not the browser. Events reach OneSignal even when a tracker blocker or a failed page unload would have dropped a client-side call, so the profile reflects what actually happened.
• One consent decision governs every destination. OneSignal is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

Complete these steps in OneSignal before configuring Signal.

Configuration

Signal Setup

Quick Setup

1. Navigate to Integrations in the sidebar.
2. Open the Integration Library tab.
3. Find OneSignal under the Marketing Automation category.
4. Click Install, and fill in the required fields.
5. Click Install Integration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/onesignal/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OneSignal",
    "variant": "default",
    "config": {
      "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "rest_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

API endpoint

POST https://api.onesignal.com/apps/{{app_id}}/custom_events

Allow egress to api.onesignal.com from the network your delivery workers run on.

Event Mapping

Blueprint 0.4.1, reviewed against the vendor’s documentation on 2026-09-23. Each preset maps the events below; every other event is dropped. Events use the canonical names from the event specs (transaction_id, value, items[], search_term); the legacy order_id, revenue and flat product fields are still read as a fallback.

Retail (ecommerce)

Product viewed, added to cart, checkout started and purchase, plus sign-up and login, as OneSignal custom events for cart and browse abandonment Journeys. Each event goes to the Custom Events API (POST /apps/{app_id}/custom_events) against the user’s External ID (the Signal user_id, required: OneSignal cannot place an event without it), with the event time and the Signal message ID as idempotency_key (as a bare UUID, without the df- prefix the Signal SDKs add). No email or phone is sent. Custom events enter users into Journeys and Wait Until steps.

Default (default)

Sign-up, login and purchase as OneSignal custom events. Each event goes to the Custom Events API (POST /apps/{app_id}/custom_events) against the user’s External ID (the Signal user_id, required: OneSignal cannot place an event without it), with the event time and the Signal message ID as idempotency_key (as a bare UUID, without the df- prefix the Signal SDKs add). No email or phone is sent. Custom events enter users into Journeys and Wait Until steps.

B2B / SaaS (saas)

Sign-up, login, trial and subscription lifecycle as OneSignal custom events. Each event goes to the Custom Events API (POST /apps/{app_id}/custom_events) against the user’s External ID (the Signal user_id, required: OneSignal cannot place an event without it), with the event time and the Signal message ID as idempotency_key (as a bare UUID, without the df- prefix the Signal SDKs add). No email or phone is sent. Custom events enter users into Journeys and Wait Until steps.

Media / Publishing (media)

Content viewed, sign-up, login and subscription as OneSignal custom events for engagement Journeys. Each event goes to the Custom Events API (POST /apps/{app_id}/custom_events) against the user’s External ID (the Signal user_id, required: OneSignal cannot place an event without it), with the event time and the Signal message ID as idempotency_key (as a bare UUID, without the df- prefix the Signal SDKs add). No email or phone is sent. Custom events enter users into Journeys and Wait Until steps.

An identified purchase (preset ecommerce) is delivered as:

POST https://api.onesignal.com/apps/8250eaf6-1a58-489e-b136-7c74a864b434/custom_events

{
  "events": [
    {
      "external_id": "crm-user-7",
      "idempotency_key": "3f2b8c1e-9d4a-4e7b-8f6a-2c1d0e9b7a65",
      "name": "purchase",
      "properties": {
        "currency": "GBP",
        "order_id": "T-1001",
        "value": 439.99
      },
      "timestamp": "2025-09-23T04:00:00Z"
    }
  ]
}

Identity

Server-side custom events for OneSignal (POST /apps/{app_id}/custom_events) against the user’s External ID (the Signal user_id), for Journey entry rules, Wait Until steps and personalisation. No email or phone is sent; events without a user_id are not sent.

Consent

OneSignal events should be sent under the marketing consent category. OneSignal manages its own per-subscription opt-in records; custom events carry no consent field, so gate the integration on the marketing category in Signal.

Verify it’s working

1. Trigger a test event from your website.
2. In OneSignal, navigate to Audience > Users and look up the test user by external ID or email.
3. View the user’s Activity and Tags to confirm Signal-delivered updates.
4. In Signal, check Live Events to confirm delivery with a 200 response status.

Troubleshooting

See also

• Airship — push notification alternative
• Braze — multi-channel engagement
• Iterable — cross-channel marketing