Skip to main content

OneSignal Push Notification API

This application provides a wrapper for the OneSignal REST API.

Available Endpoints​

Currently, the application exposes two endpoints for sending push notifications:

  • Create notification
  • Retrieve delivery status

Authentication​

Endpoints are secured using JWT (JSON Web Token) authentication. This is already implemented in the Aleteia platform.

Refer to this example for implementation.

The payload should contain only the application_id, and you must include the exp claim (short expiration, e.g., 1–2 minutes) to prevent replay attacks.

The JWT must be sent in the Authorization header prefixed with Bearer. Example here.

Create Notification​

POST https://reports.aleteia.org/push_notifications/:application_id/create

Parameters (as JSON):

{
  "notification": {
    "title": "Notification Title",
    "message": "Test Notification",
    "link": "http://example.com",
    "image": "http://placehold.it/256x256?text=Icon",
    "web_image": "http://placehold.it/1024x768?text=Big+Image",
    "locale": "it"
  }
}

Response​

HTTP 201 with JSON:

{
  "id": 2,
  "message": "Some message",
  "link": "http://example.com",
  ...
}

Error: HTTP 422 (validation) or HTTP 403 (auth error).

Retrieve Notification Status​

GET https://reports.aleteia.org/push_notifications/:id

Response format:

{
  "id": 5,
  "title": "Notification Title",
  "message": "Final development test",
  ...
  "full_status": {
    "delivery_status": "completed",
    ...
  }
}

App Management & v2 Key Provisioning​

The application maintains a local mirror of OneSignal apps (OneSignalApplication records) and supports two API key variants per app:

  • REST key (basic_auth_key) — legacy v1 key, stored encrypted with attr_encrypted
  • v2 API key (v2_api_key) — newer key provisioned via the OneSignal Organization API, stored with Active Record encryption

When a v2 key is present it takes precedence; the client falls back to the legacy key otherwise.

Synchronization​

OneSignalApplication.synchronize pulls the current app list from the OneSignal Organization API, filters to apps matching the current environment (production apps in production, staging/other apps elsewhere), and upserts them locally. New apps get a v2 key provisioned automatically during creation.

Reconcile Maintenance Task​

The Maintenance::OneSignal::ReconcileAppsTask maintenance task (available at /maintenance_tasks) processes each existing DB record and:

  • Provisions a v2 key for apps that are in scope for the current environment but don't have one yet
  • Deletes apps that are out of scope for the current environment

Run this task once after deploying the v2 key migration to backfill existing records.

Required ENV Variable​

The Organization API requires ONE_SIGNAL_ORG_KEY — an org-level key distinct from the per-app REST keys.