​
Overview

The OneSignal + Amazon Athena integration enables automatic syncing of custom events from your Athena data lake 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 AWS data infrastructure. 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

​
Amazon Athena

  • AWS Account with Athena access
  • Athena Workgroup configured (default: “primary”)
  • S3 Query Results Bucket for Athena query outputs
  • IAM Permissions for Athena, S3, and AWS Glue access
  • Event data stored in S3 and cataloged in AWS Glue

​
Setup

​
Configure AWS permissions

OneSignal needs specific permissions to query your event data through Athena. Create an IAM policy with the following permissions:
1

Create IAM policy

Create an IAM policy that includes these permissions:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "athena:StartQueryExecution",
                "athena:GetQueryExecution",
                "athena:GetQueryResultsStream",
                "athena:GetQueryResults",
                "athena:CreatePreparedStatement",
                "athena:DeletePreparedStatement",
                "glue:GetTable",
                "glue:GetTables",
                "glue:GetDatabase",
                "glue:GetDatabases",
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:glue:<region>:<aws-account-id>:table/<database>/*",
                "arn:aws:glue:<region>:<aws-account-id>:database/<database>",
                "arn:aws:glue:<region>:<aws-account-id>:catalog",
                "arn:aws:athena:<region>:<aws-account-id>:workgroup/<workgroup>",
                "arn:aws:s3:::<query-results-bucket>",
                "arn:aws:s3:::<query-results-bucket>/*",
                "arn:aws:s3:::<event-data-bucket>",
                "arn:aws:s3:::<event-data-bucket>/*"
            ]
        }
    ]
}
Replace the placeholders with your actual AWS region, account ID, database name, workgroup, and bucket names.
2

Create IAM user or role

Create an IAM user for OneSignal and attach the policy created above, or prepare to use role-based access.
3

Note connection details

Collect the following information:
  • AWS Access Key ID and Secret Access Key (if using IAM user)
  • S3 Query Results Bucket URL
  • AWS Region
  • Athena Workgroup (default: “primary”)

​
Configure OneSignal Athena connection

1

Navigate to integrations

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

Select Amazon Athena

Choose Amazon Athena from the list of available integrations.
3

Enter connection details

Provide your Athena connection information:
  • AWS Access Key ID: Your IAM user access key
  • AWS Secret Access Key: Your IAM user secret key
  • AWS Region: Your Athena region
  • S3 Query Results Bucket: URL for query outputs
  • Athena Workgroup: Your workgroup name
4

Test the connection

Click Test Connection to verify OneSignal can access your Athena instance and execute queries.

​
Alternative: Role-based access

For enhanced security, you can use IAM roles instead of access keys:
1

Enable role-based access

In the Athena connection settings, check Use Role and leave the access keys blank.
2

Create IAM role

In the AWS Console, create an IAM role with:
  • Trusted Entity: Another AWS Account
  • Account ID: 341876425553 (OneSignal’s AWS account)
  • External ID: The ID shown in OneSignal (appears after initial connection attempt)
  • Permissions: The IAM policy created above
3

Complete the connection

Enter the Role ARN in OneSignal and test the connection.

​
Event Data Mapping

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

Select event tables

Choose the tables or views containing your event data that you want to sync to OneSignal.
2

Map required event fields

Map the required fields for custom events:
  • Event Name: Column containing the event type (e.g., “purchase”, “signup”)
  • User Identifier: External User ID, Email, or Phone Number column
  • Event Timestamp: When the event occurred (optional)
3

Map event payload data

Map additional columns to event payload properties:
  • Custom event properties (product_id, price, category, etc.)
  • Contextual data (source, campaign, etc.)
  • Behavioral metrics (value, quantity, etc.)
4

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

  • Query Performance: Athena charges per query and data scanned - optimize your event tables
  • S3 Dependencies: Requires properly configured S3 buckets and Glue catalog
  • Data Freshness: Event sync frequency depends on how often your S3 data is updated

​
FAQ

​
What happens if my Athena queries fail?

OneSignal will log query errors and retry failed queries. Check your IAM permissions and S3 bucket access if you encounter persistent failures.

​
How often does OneSignal sync events?

OneSignal checks for new events 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 Athena integration setup.