Pub/Sub

Sync custom events from Google Pub/Sub to OneSignal to trigger automated Journeys and personalized messaging campaigns based on real-time user behavior.

Overview

The OneSignal + Google Pub/Sub integration enables real-time syncing of custom events from your Pub/Sub topics to OneSignal to trigger automated messaging campaigns and Journeys based on user behavior.

Pub/Sub is Google’s scalable messaging service that allows applications to send and receive messages between independent components. OneSignal acts as a subscriber to your Pub/Sub topics, allowing you to sync event messages from Pub/Sub to trigger personalized user experiences.

---

Requirements

• Access to Custom Events (currently in beta)
• Updated Account Plan (not available on free apps).

Google Pub/Sub

• Google Cloud Project with Pub/Sub enabled
• Pub/Sub topics containing event messages
• IAM permissions to grant service account access
• JSON-formatted messages on your topics

---

Setup

1. Create Pub/Sub connection

   In OneSignal, go to Data > Integrations and click Add Integration.

   1. Select Google Pub/Sub from the list
   2. Enter the GCP Project ID where your Pub/Sub topics are located
   3. Choose authentication method:
      • Auto-generated Service Account (recommended): OneSignal creates and manages the service account
      • Existing Service Account: Provide your own service account key JSON file
   4. Click Connect
2. Grant permissions to service account

   OneSignal will create a new service account and provide you with the service account email address.

   Grant the roles/pubsub.editor role to this service account on your GCP project:

   gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
     --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
     --role roles/pubsub.editor
   

   OneSignal uses this role to:

   • Create subscriptions to your event topics
   • Consume event messages from topics
   • Create error topics (Dead Letter Queue) for failed processing
3. Test connection

   Once you’ve granted the necessary permissions, click Save in OneSignal to verify the connection.

   OneSignal will validate that it can access your Pub/Sub topics and is ready to process event messages.

---

Event Data Schema

Before you can use a Pub/Sub topic for custom events, you must define the schema of the event messages.

1. Navigate to event schema definition

   In OneSignal, go to Data > Integrations and select your Pub/Sub connection.

   OneSignal automatically pulls the list of topics from your project. Click Refresh topics to manually refresh the list.

2. Define event message schema

   1. Click on the name of the topic containing your event data
   2. Select JSON as the message format (only supported format)
   3. Click Import sample message and provide a sample event message
   4. Review the detected schema to ensure proper field mapping
   5. Click Save Dataset

Event Message Format

Your Pub/Sub messages should follow this JSON structure for OneSignal custom events:

{
  "event_name": "purchase_completed",
  "user_id": "user_12345",
  "timestamp": "2023-12-01T10:30:00Z",
  "properties": {
    "product_id": "prod_abc123",
    "price": 29.99,
    "category": "electronics",
    "payment_method": "credit_card"
  },
  "session_id": "session_789"
}

Event data mapping

Map your to OneSignal’s custom events format:

OneSignal Field	Description	Required
name	event_name	Event identifier	Yes
external_id	user_id	User identifier	Yes
timestamp	event_timestamp	When event occurred	No
properties	event_data	No

Do not include customer PII or sensitive data in sample messages. OneSignal stores message samples as part of the dataset definition.

---

Real-time Event Processing

Unlike batch integrations, Pub/Sub enables near real-time event processing:

• Low Latency: Events are processed within seconds of being published to topics
• Automatic Subscriptions: OneSignal creates dedicated subscriptions for each topic
• Error Handling: Failed events are sent to Dead Letter Queue topics for investigation
• Scalable Processing: Handles high-volume event streams automatically

---

Advanced Configuration

Dead Letter Queue

OneSignal automatically creates error topics for events that fail processing:

• Automatic Creation: Error topics are created per subscription
• Failed Event Storage: Events that can’t be processed are stored for debugging
• Manual Review: Access failed events through Google Cloud Console for troubleshooting

Message Acknowledgment

OneSignal handles Pub/Sub message acknowledgment automatically:

• Successful Processing: Messages are acknowledged after successful event creation
• Failed Processing: Messages are negatively acknowledged and sent to Dead Letter Queue
• Retry Logic: Built-in retry handling for transient failures

---

Limitations

• Only JSON message format is supported
• Message samples are stored as part of dataset definitions (avoid PII)
• Requires roles/pubsub.editor permissions at project level
• Maximum message size follows Google Pub/Sub limits (10MB)

---

FAQ

How quickly are events processed?

Events are typically processed within seconds of being published to your Pub/Sub topic, enabling near real-time Journey triggering.

What happens if OneSignal can’t process an event?

Failed events are automatically sent to a Dead Letter Queue topic that OneSignal creates. You can review these events in the Google Cloud Console for debugging.

Can I use multiple topics for different event types?

Yes, you can define schemas for multiple topics within the same GCP project. Each topic can contain different event types with their own schema definitions.