​
Overview

The OneSignal + Amazon S3 integration enables automatic syncing of custom events from CSV files stored in your S3 bucket directly to OneSignal’s Custom Events API. This allows you to trigger automated Journeys and personalized messaging campaigns based on real user behavior stored in your data warehouse. You can sync events like purchases, product views, subscription changes, or any custom user actions to automatically trigger onboarding sequences, re-engagement campaigns, transactional messages, and targeted promotions across push notifications, email, in-app messages, and SMS.

​
Requirements

​
OneSignal

  • Custom Events feature enabled (currently in beta - contact support@onesignal.com)

​
Amazon S3

  • AWS Account with S3 bucket access
  • IAM permissions to create roles and policies
  • CSV files with event data formatted according to OneSignal requirements
  • UTF-8 encoded comma-delimited files with .csv extension

​
Setup

​
Prepare your event CSV files

Your S3 bucket must contain properly formatted CSV files with event data that OneSignal can process: File Format Requirements:
  • Uncompressed, UTF-8 encoded, comma delimited CSV with .csv file extension
  • Include a header row (OneSignal will use headers as event field names)
  • Represent null values with the string #N/A
  • Values containing commas should be wrapped in double quotes
  • Values containing double quotes should be escaped with a second double quote
File Structure: OneSignal treats each folder path as a unique data source and considers the file name to be a version of the data within that path. When processing events, OneSignal will always select the newest data in the selected folder path based on timestamp. When updating event data in S3, you can either replace the existing file or add a newer version. OneSignal will process the new events and send them to the Custom Events API.

​
Create IAM role for OneSignal

OneSignal uses role-based authentication to connect to your S3 bucket, following AWS security best practices.
1

Create the IAM role

Create an IAM role in your AWS account that provides read-only access to your S3 bucket for OneSignal’s AWS Account ID (341876425553):
aws iam create-role \
  --role-name OneSignalS3DataImport \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
      "Action": "sts:AssumeRole"
    }]
  }'
Save the returned Role ARN as you’ll need it for the OneSignal configuration.
2

Grant S3 permissions

Grant your newly-created role read-only access to your S3 bucket:
aws iam put-role-policy \
  --role-name OneSignalS3DataImport \
  --policy-name OneSignalS3Access \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }]
  }'
Replace YOUR_BUCKET_NAME with your actual S3 bucket name.

​
Configure OneSignal S3 connection

1

Navigate to Data Sources

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

Select Amazon S3

Choose Amazon S3 from the list of available integrations.
3

Enter connection details

Provide the following information:
  • Region: Your S3 bucket region
  • Bucket Name: Your S3 bucket name
  • Role ARN: The IAM role ARN from Step 1
  • Prefix: The folder path containing your event CSV files (optional)
4

Complete the security handshake

OneSignal will generate a unique external ID and display it on the next screen. Update your IAM role to require this external ID:
aws iam update-assume-role-policy \
  --role-name OneSignalS3DataImport \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
      "Action": "sts:AssumeRole",
      "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
    }]
  }'
Replace GENERATED_EXTERNAL_ID with the external ID shown in the OneSignal dashboard.
5

Test the connection

Click Test Connection in OneSignal to verify the setup is working correctly.

​
CSV Processing Modes

OneSignal supports two modes when reading event CSV files from your S3 bucket:

​
Most Recent (Default)

OneSignal processes only the most recent file in the configured S3 prefix and folder group. The single file is interpreted as the complete set of events to process. This mode works well when:
  • A single file contains all events for a time period
  • New versions of files are added over time with updated event data
  • You want to process a complete batch of events at once

​
Merge All

OneSignal takes every file in the configured S3 prefix and folder group and merges them into a single dataset before processing events. This mode is useful when:
  • Your event data has been split into multiple files
  • You want to process events from multiple sources
  • Files are being added incrementally with new events
In Merge All mode, all CSV files must have the exact same column names and order.

​
Event Data Mapping

Once connected, you’ll need to map your CSV columns to OneSignal custom event fields:
1

Review detected fields

OneSignal will automatically detect columns from your event CSV files and suggest mappings.
2

Map required event fields

Map the required fields for custom events:
  • Event Name (required): The name/type of the event
  • External ID (required): External User ID
  • Event Timestamp (optional): When the event occurred. Otherwise, assumed to be now.
3

Configure sync settings

Set your event processing frequency and delivery preferences.

​
Event data mapping

Map your to OneSignal’s custom events format:
OneSignal FieldDescriptionRequired
nameevent_nameEvent identifierYes
external_iduser_idUser identifierYes
timestampevent_timestampWhen event occurredNo
propertiesevent_dataNo

​
Limitations

  • SQL Queries: S3 sources do not support SQL queries or advanced transformations on event data
  • File Size: Individual CSV files should not exceed 1GB
  • Update Frequency: Minimum sync interval is 15 minutes
  • File Types: Only CSV files are supported (no JSON, Parquet, etc.)

​
FAQ

​
What happens if my CSV file has formatting errors?

OneSignal will skip malformed rows and provide detailed error logs in the integrations dashboard. Common issues include missing required columns, invalid timestamp formats, and inconsistent column counts.

​
How often does OneSignal check for new files?

OneSignal checks your S3 bucket based on your configured sync frequency, with a minimum interval of 15 minutes.

​
Need help?

Contact our support team at support@onesignal.com or use the in-app chat for assistance with your S3 integration setup.