.png)
OneSignal Integration Guide
Connect OneSignal with enterprise systems through REST APIs, selected Event Stream notifications, and Martini workflows for customer messaging and engagement automation.
OneSignal integration options at a glance
OneSignal's primary integration mechanism is its REST API, which supports applications, users, subscriptions, aliases, messages, segments, tags, and message-related information. Event Streams provide outbound delivery for selected events, including supported delivery, click, and failure activity, but they are not a universal change feed. Notification requests can target multiple users, aliases, subscriptions, or segments, supporting targeted and broadcast-style messaging rather than unrestricted bulk CRUD. OneSignal uses API keys together with application or organization identifiers, depending on the endpoint. Martini can consume these APIs, receive configured Event Stream notifications through an API, map and transform data, apply business rules, and orchestrate retries and downstream updates.
| Integration point | Supported by OneSignal? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Manage Apps, Users, Subscriptions, Aliases, Messages, Segments, tags, and message-related information. REST is the primary mechanism for sending notifications and synchronizing OneSignal data. | Martini can consume the OneSignal REST API from workflows, map request and response payloads, expose reusable APIs, and apply validation, routing, and error handling. |
| Webhooks / outbound callbacks | Limited | Event Streams can deliver selected OneSignal events, such as supported delivery, click, or failure activity, to external destinations including webhook-style HTTP endpoints. | Martini can expose an API endpoint to receive configured Event Stream notifications, validate inbound requests, transform payloads, and route events to downstream systems. |
| Bulk / async notification requests | Limited | A notification request can target multiple users, aliases, subscriptions, or segments. This supports broadcast and targeted messaging but is not unrestricted bulk CRUD across all objects. | Martini can construct recipient and message payloads, control concurrency, persist returned message identifiers, and orchestrate later status retrieval or event processing. |
| Authentication | Yes | Server-to-server access uses API keys, while endpoints may also require an app ID, organization API key, or User Auth Key depending on scope and operation. | Martini can store OneSignal keys and application identifiers in protected secrets or environment configuration and apply endpoint-specific authentication. |
| Database / analytics access | Limited | Message and engagement information is available through OneSignal APIs or event delivery. No direct customer database connection was confirmed. | Martini can retrieve API-based status and engagement information or process Event Stream data, but should not use JDBC as a OneSignal access method. |
| File / attachment APIs | Not confirmed | No general-purpose OneSignal file or attachment API was confirmed. Some channel payloads may reference media or external content. | Martini can map supported message content references but should treat files and binary assets as managed by another system. |
| GraphQL APIs | Not confirmed | No official OneSignal GraphQL API was confirmed in the reviewed documentation. | Martini should use the documented OneSignal REST APIs rather than assume GraphQL access. |
| SOAP APIs | No | No official OneSignal SOAP API was confirmed. | Martini should not design a OneSignal SOAP integration; use REST APIs or configured Event Stream delivery instead. |
How OneSignal exposes data and business events
OneSignal REST APIs
OneSignal documents REST APIs for applications, users, subscriptions, aliases, messages, segments, and related message information. These APIs are the primary integration mechanism for sending communications and synchronizing customer and engagement data.
Martini implementation pattern
Martini implementation pattern: a workflow or Martini API receives a business event, authenticates with the appropriate OneSignal API key and app or organization identifier, resolves the target object, maps the payload, invokes the REST endpoint, and stores identifiers or status data for later processing.
Implementation sequence
OneSignal Event Streams
OneSignal Event Streams can deliver selected events to external destinations, including webhook-style HTTP endpoints where configured. Coverage depends on the enabled event types and is not a universal feed for every OneSignal object or state change.
Martini implementation pattern
Martini implementation pattern: expose a secured Martini API for the configured Event Stream destination, validate and normalize each event, tolerate duplicates or out-of-order delivery, and route engagement activity to a CRM, customer data platform, analytics store, or operational database.
Implementation sequence
Bulk notification requests
OneSignal notification requests can target multiple users, aliases, subscriptions, or segments in one request. This provides targeted or broadcast-style messaging but does not represent unrestricted bulk CRUD for all OneSignal objects.
Martini implementation pattern
Martini implementation pattern: a workflow assembles eligible recipients, validates payload and recipient limits, controls concurrency, submits the notification request, and records the returned message identifier for status tracking and duplicate prevention.
Implementation sequence
Common OneSignal integration patterns
Pattern 1: Send lifecycle notifications
When to use this pattern
Use this pattern when a CRM, commerce platform, or customer database produces events such as registration, renewal, shipment, abandoned cart, or account security activity that should trigger a targeted OneSignal message.
Integration direction
Example Mapping
| OneSignal Field | Canonical Field | Target Field |
|---|---|---|
| sourceEventId | event.id | external_id or idempotency reference |
| customerId | customer.externalId | alias.external_id |
| eventType | notification.reason | message data or template selection |
| preferredChannel | channel.preference | channel-specific message payload |
Martini implementation pattern
Martini receives the source event, validates its identity and eligibility, resolves the OneSignal user through an alias, applies consent and business rules, selects or builds the channel-specific message, and calls OneSignal. The workflow stores the message ID and uses bounded retries for rate limits or transient failures while avoiding duplicate sends.
Martini capabilities used
- API consumption
- workflows
- data mapping
- business rules
- secrets management
- error handling
Pattern 2: Synchronize users and subscriptions
When to use this pattern
Use this pattern when customer profile, contact-channel, consent, or subscription changes in a source system must be reflected in OneSignal Users, Aliases, Subscriptions, tags, or user properties.
Integration direction
Example Mapping
| OneSignal Field | Canonical Field | Target Field |
|---|---|---|
| customer.id | customer.externalId | alias.external_id |
| contact.email | email subscription address | |
| phone | contact.phone | SMS subscription number |
| customerTier | profile.segment | tag or user property |
Martini implementation pattern
A scheduled or event-triggered Martini workflow retrieves changed source data, normalizes channel-specific values, uses stable aliases for identity resolution, and updates the relevant OneSignal objects. Validation rejects incomplete contact data, while source checkpoints and idempotent keys make reruns safe.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- validation
- business rules
- error handling
Pattern 3: Synchronize engagement events
When to use this pattern
Use this pattern when selected OneSignal delivery, click, or failure events must update customer, analytics, or operational systems without repeatedly polling OneSignal for every event.
Integration direction
Example Mapping
| OneSignal Field | Canonical Field | Target Field |
|---|---|---|
| event.type | engagement.eventType | activity.type |
| message_id | message.providerId | OneSignal message ID |
| onesignal_id | customer.externalId | contact or customer identifier |
| event.timestamp | engagement.occurredAt | activity timestamp |
Martini implementation pattern
OneSignal Event Streams deliver configured events to a secured Martini API. Martini validates the event, normalizes identifiers and timestamps, handles duplicates or out-of-order delivery, enriches the payload when needed, and writes the activity to the target system with processing status and error routing.
Martini capabilities used
- API exposure
- webhook consumption
- workflows
- data transformation
- deduplication
- error handling
Pattern 4: Centralize notification orchestration
When to use this pattern
Use this pattern when multiple applications should call one controlled API instead of embedding OneSignal credentials, targeting conventions, consent checks, and retry logic in each application.
Integration direction
Example Mapping
| OneSignal Field | Canonical Field | Target Field |
|---|---|---|
| recipient | notification.recipient | user, alias, subscription, or segment |
| templateKey | notification.template | OneSignal template or message payload |
| priority | notification.priority | channel and routing rules |
| sourceReference | notification.sourceId | message data and audit record |
Martini implementation pattern
Martini exposes an internal API that validates notification requests, checks preferences and eligibility, selects the channel and target, loads protected environment configuration, invokes OneSignal, and returns a controlled response. Reusable workflows centralize audit logging, retry behavior, and provider-specific mappings.
Martini capabilities used
- API exposure
- workflows
- data mapping
- business rules
- secrets management
- monitoring
Applications commonly integrated with OneSignal
OneSignal can be integrated with customer, commerce, service, and operational applications to trigger communications and distribute engagement outcomes. The exact event and API coverage should be validated for each application and OneSignal configuration.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Send customer, sales, or service-triggered notifications and write selected OneSignal engagement events back to customer records. | Salesforce → Martini → OneSignal | Martini receives Salesforce events or retrieves relevant data, resolves the OneSignal user through an external ID or alias, validates channel and consent rules, and calls the OneSignal REST API. Selected Event Stream activity can be transformed and written back to Salesforce. |
| HubSpot | Trigger lifecycle, marketing, or customer-engagement notifications from contact and campaign activity. | HubSpot → Martini → OneSignal | A Martini workflow consumes HubSpot data or events, maps contact identifiers, tags, and preferences to OneSignal users and subscriptions, and creates channel-specific messages while recording the returned message identifier. |
| Shopify | Notify customers about order status, shipment, promotions, abandoned carts, or fulfillment events. | Shopify → Martini → OneSignal | Martini receives or retrieves Shopify order events, applies notification eligibility and deduplication rules, resolves the customer alias, and invokes the OneSignal notification API with the appropriate payload. |
| ServiceNow | Send incident, request, approval, or employee-service notifications and record selected delivery outcomes. | ServiceNow → Martini → OneSignal | Martini orchestrates ServiceNow events into OneSignal messages, applies routing and recipient rules, and can process selected OneSignal Event Stream events before updating ServiceNow activity or status data. |
| NetSuite | Send order, invoice, fulfillment, or account notifications based on ERP events. | NetSuite → Martini → OneSignal | Martini transforms NetSuite business events into OneSignal user, alias, tag, and message models, validates channel-specific fields, and applies bounded retries for transient API failures. |
| Segment | Exchange customer traits and behavioral events for notification targeting or distribute OneSignal engagement activity to downstream destinations. | Segment → Martini → OneSignal | Martini receives the selected Segment event or profile payload, normalizes identifiers and traits, applies targeting rules, and synchronizes eligible data with OneSignal while preserving source event IDs. |
| Jira | Send issue, release, or operational notifications to subscribed users or teams. | Jira → Martini → OneSignal | Martini consumes Jira events, maps project and issue context into a controlled notification request, resolves aliases or segments, and logs the OneSignal message ID for audit and follow-up processing. |
How to build a OneSignal integration in Martini
Objective
Configure the OneSignal app ID and endpoint-specific API key without embedding credentials in workflow mappings or client applications.
Instructions in Martini
- Store OneSignal keys and application identifiers in Martini secrets or protected environment configuration.
- Confirm whether the endpoint requires an app-level, organization-level, or user authentication key.
- Separate development, test, and production OneSignal applications where appropriate.
Objective
Select an event-driven API, Event Stream, or scheduled trigger that matches the synchronization or notification requirement.
Instructions in Martini
- Use a Martini API or workflow trigger for source-system events.
- Expose a secured Martini API for configured OneSignal Event Stream delivery.
- Use a scheduler for incremental retrieval when no suitable event is available.
Objective
Obtain the current OneSignal or source-system data required to resolve identity, determine eligibility, or process engagement activity.
Instructions in Martini
- Resolve users through stable aliases or external identifiers.
- Retrieve message or engagement information when the workflow needs current status.
- Persist cursors, timestamps, or message identifiers for incremental processing.
Objective
Coordinate validation, identity resolution, targeting, API calls, downstream writes, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Separate provider-specific OneSignal calls from business rules and downstream mappings.
- Route channel-specific push, email, SMS, and in-app payloads through appropriate branches.
- Capture source event IDs and OneSignal message IDs for audit and deduplication.
Objective
Convert source customer, event, and engagement models into OneSignal Users, Subscriptions, Aliases, Messages, Segments, tags, and user properties.
Instructions in Martini
- Normalize identifiers, timestamps, contact values, and channel fields.
- Use reusable mappings for current Users, Subscriptions, and Aliases terminology.
- Validate required fields before sending channel-specific message payloads.
Objective
Enforce consent, preferences, notification eligibility, recipient limits, and duplicate-prevention logic before customer-facing communication occurs.
Instructions in Martini
- Treat the designated source system as authoritative for consent and preferences.
- Reject or route incomplete recipient data for review.
- Use stable source event IDs and supported idempotency behavior where available.
Common OneSignal data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Apps | Represent mobile, web, or other messaging-enabled applications and provide application scope for API operations. | Martini, Salesforce, HubSpot, Shopify, ServiceNow | Martini stores the relevant app ID in protected configuration, routes requests to the correct environment, and keeps application-specific mappings reusable. |
| Users | Represent end users who may receive OneSignal communications across supported channels. | Salesforce, HubSpot, Shopify, Segment, customer databases | Martini maps stable source identifiers to OneSignal users, applies preference and consent rules, and performs repeatable updates rather than matching on mutable display fields. |
| Subscriptions | Represent channel subscriptions such as push, email, or SMS delivery relationships. | Customer platforms, commerce systems, support applications | Martini normalizes channel-specific fields, validates subscription state and contact data, and avoids assuming that all subscription types share the same lifecycle. |
| Aliases | Associate an external customer or business identifier with a OneSignal user. | Salesforce, Shopify, NetSuite, HubSpot, customer databases | Martini uses stable aliases for identity resolution and idempotent synchronization, storing source-to-OneSignal relationships where required. |
| Messages | Represent notifications and other outbound messages sent through OneSignal. | Salesforce, ServiceNow, analytics stores, operational databases | Martini builds channel-specific payloads, records returned message identifiers, and processes later status or event information without treating an accepted request as proof of delivery. |
| Segments | Target groups of users based on subscriptions, tags, behavior, or other criteria. | Customer engagement platforms, commerce systems, internal notification APIs | Martini applies business rules to select users, aliases, subscriptions, or segments and invokes the notification API with controlled targeting. |
Authentication and security considerations
Endpoint-specific credentials
OneSignal access can require an API key together with an app ID, organization API key, or User Auth Key, depending on the endpoint and scope.
Protected configuration
Store OneSignal keys and application identifiers in Martini secrets or protected environment configuration. Do not expose server-side keys in browser applications or public notification endpoints.
API boundary protection
Secure Martini APIs that accept notification requests or Event Stream events. Validate inbound requests, restrict who can trigger customer-facing messages, and separate non-production and production credentials.
Operational considerations for OneSignal integrations
Rate limits and retries
Handle HTTP 429 responses with controlled concurrency and bounded backoff. Do not blindly retry authentication, validation, or recipient-data errors.
Pagination and checkpoints
Use incremental retrieval for list and history operations where applicable. Persist opaque cursors, timestamps, or message identifiers rather than repeatedly loading the full OneSignal population.
Idempotency and delivery state
Store source event IDs and returned message identifiers to prevent duplicate notifications. An accepted API response does not necessarily prove end-user delivery; use status information or configured Event Stream events for outcome processing.
Schema and channel changes
Keep provider-specific mappings isolated and test changes to Users, Subscriptions, Aliases, tags, and message payloads in a non-production OneSignal application. Push, email, SMS, and in-app messages have different payload and recipient requirements.
Why use Martini instead of scripts or point-to-point integrations?
Centralized integration logic
Martini centralizes OneSignal authentication, identity resolution, notification eligibility, channel routing, and provider-specific mappings instead of duplicating them across scripts or applications.
Reusable workflows and APIs
Teams can expose a controlled notification API, receive selected Event Stream events, and reuse workflows for customer synchronization, message submission, status processing, and downstream updates.
Operational control
Martini provides workflow orchestration, transformation, validation, error handling, retry design, protected configuration, and monitoring patterns that are difficult to maintain consistently in point-to-point scripts.
Frequently asked questions
OneSignal can be integrated primarily through its REST APIs for Apps, Users, Subscriptions, Aliases, Messages, Segments, tags, and message information. Event Streams can deliver selected delivery, click, or failure events to configured external destinations, including webhook-style HTTP endpoints. Notification requests can target multiple recipients or segments.
Yes. Martini can consume OneSignal REST APIs, expose a secured API for configured OneSignal Event Stream notifications, map customer and engagement data, and orchestrate notification workflows. A dedicated native Martini connector is not documented in the supplied materials.
No. A dedicated OneSignal connector is not required. Martini can integrate using OneSignal's confirmed REST APIs, API-key authentication, application identifiers, and selected Event Stream delivery mechanisms.
Lonti does not charge an additional per-connector or per-vendor fee to integrate OneSignal. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from OneSignal, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
REST APIs are the primary documented method for sending messages and managing OneSignal data. Event Streams are appropriate for selected outbound delivery, click, or failure events. OneSignal does not have a confirmed official GraphQL API, and no SOAP API was confirmed.
OneSignal supports Event Streams for selected event types and destinations, including webhook-style HTTP delivery where configured. Coverage depends on the enabled event types and account configuration, so Event Streams should not be treated as a universal webhook for every object or state change.
Martini can synchronize source customer and contact data into OneSignal Users, Aliases, Subscriptions, tags, and user properties through event-driven or scheduled workflows. Stable external identifiers, incremental checkpoints, pagination handling, and source event IDs support repeatable synchronization.
Martini can distinguish transient network and rate-limit responses from authentication or validation failures, apply bounded backoff for retryable failures, and route non-retryable errors for review. Workflows can store source event IDs and OneSignal message IDs and use supported idempotency behavior where available to reduce duplicate notifications.
Related Martini documentation
Workflows
Connect OneSignal with your enterprise systems
Use Martini to build maintainable OneSignal integrations for customer synchronization, notification orchestration, and engagement event processing.