Showing content from https://documentation.onesignal.com/docs/onesignal-api below:
REST API Overview - OneSignal
Our REST API follows the REST Architecture and provides programmatic access to core messaging and user features. Use the API to send push notifications, emails, and SMS, manage users, subscriptions, and segments, export data, and configure apps. RequirementsGeneral
- HTTPS Required: All API requests must use HTTPS with TLS 1.2 or higher, on port
443.
- Network Access: Firewalls or proxies must allow outbound traffic to
https://api.onesignal.com on port 443.
- DNS TTL: Clients must respect OneSignal’s DNS TTL of 300 seconds to avoid stale IP resolution.
Incoming Traffic to OneSignal (API & SDK Requests) All incoming API traffic—whether from your backend, our SDKs, or the dashboard—passes through Cloudflare, which serves as our global edge network.
- You may see Cloudflare IP addresses in logs.
- These IPs are managed by Cloudflare and may change over time.
- If you maintain a strict firewall and need to allow outbound traffic to OneSignal, use Cloudflare’s official IP ranges:
https://www.cloudflare.com/ips/
We do not recommend whitelisting specific Cloudflare IPs, as they may change without notice.
Outgoing Traffic from OneSignal (Webhooks & Event Streams) For features where OneSignal sends HTTP requests to your servers (e.g., webhooks or event streams), these originate from our infrastructure on Google Cloud Platform (GCP) in the europe-west4 region (Groningen, Netherlands).
Platform-specific network requirements FCM (Google Android and Chrome push)
APNs (Apple iOS, iPadOS, Safari push)
- Required ports:
5223, 443, and 2197
- Recommended servers:
- Sandbox:
api.sandbox.push.apple.com:443
- Production:
api.push.apple.com:443
- IP range:
17.0.0.0/8
- More info:
Core API capabilities Send messagesSee our Create Message guide to get started. Programmatically send: Supported featuresBelow are common supported features for each platform. See our overview docs for each platform’s supported features:
Manage templatesTemplates are reusable push, email, and SMS messages that simplify development and improve consistency. Manage users and subscriptionsSee our Users and Subscriptions guides for more details. Manage segmentsSegments help group users by filters. You can also target users dynamically using filters without creating persistent segments. Export dataFor analytics breakdowns, see Analytics overview. Manage apps & keysOneSignal allows you to group platforms (mobile apps, websites) under a single App ID. See Apps, orgs, & accounts. API key management See Keys & IDs for more details. Reliability and delivery Rate limitsAll API endpoints are subject to rate limits. Limits vary by endpoint and request type. Refer to the Rate Limits reference for full details.
Rate limits are returned via response headers. Be sure to implement exponential backoff retry logic based on Retry-After.
RetriesIf a request fails due to a temporary server error (HTTP 5xx) or a rate limit (HTTP 429), you should retry the request using an exponential backoff strategy. For rate limits, always wait the amount of time specified in the Retry-After header before retrying.
- HTTP 429 (Too Many Requests):
- Wait for the duration specified in the Retry-After header before retrying.
- Use the
idempotency_key to prevent sending duplicate messages when retrying.
- HTTP 5xx (Server Errors):
- Retry the request using exponential backoff (e.g., start with 60 seconds and increase the wait time after each failure).
- Do not retry HTTP 4xx errors (such as 400, 401, or 403) unless you have fixed the underlying issue in your request, as these indicate a problem with your request rather than a temporary server issue.
- If you do not get a response from our API within 100 seconds, you can retry the request. We recommend using an
idempotency_key to prevent sending duplicate messages when retrying.
Idempotent requestsUse the idempotency_key header to prevent duplicate messages when retrying failed requests.
- Available for: Create Message
- Format: Up to 64 alphanumeric characters
- Duration: Idempotency keys are cached for 24 hours
See the Idempotent Notification Requests guide for implementation tips. FAQ What is the timeout for API responses?
- Default: 100 seconds
- If you’re unsure whether a request completed, use an
idempotency_key to safely retry.
Do I need to download or renew certificates to call the OneSignal API?No, you do not need to manually download or renew certificates to call the OneSignal API. Our API uses HTTPS with a publicly trusted TLS certificate managed by Cloudflare. These edge certificates are renewed automatically by Cloudflare and trusted by all major browsers, operating systems, and runtimes. No extra action is needed unless your environment has special trust or pinning rules. Why you might be seeing frequent certificate changes If your network or middleware is configured to pin a specific leaf certificate (the one shown during the TLS handshake), you will see it expire and rotate every few months. This is normal — Cloudflare rotates these certificates for security. Most clients trust the public root and intermediate Certificate Authorities (CAs) instead, which avoids any impact when the leaf cert changes. Recommended approach
- Best practice: Trust the root and intermediate CAs in the chain instead of the rotating leaf certificate. This allows certificate rotation without breaking your connection.
- If you must pin a certificate: Pin the public key (SPKI) of the CA or use a backup key set, not the exact leaf certificate.
Workaround: Fetching the current certificate If your process requires the active leaf certificate, you can retrieve it directly from our API endpoint:
SERVERNAME=api.onesignal.com
echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/${SERVERNAME}_current.pem
To retrieve the full certificate chain, add the -showcerts flag to openssl s_client and capture all certificates printed. More information Cloudflare’s documentation explains how their SSL/TLS certificates work and why they rotate:
RetroSearch is an open source project built by @garambo
| Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4