--- title: Configuring a custom push notification provider (early access) description: Configure a custom push notification provider for PingOne MFA for sending push notifications. component: pingone page_id: pingone:early-access-features:ea-p1_configure_custom_push_provider canonical_url: https://docs.pingidentity.com/pingone/early-access-features/ea-p1_configure_custom_push_provider.html llms_txt: https://docs.pingidentity.com/pingone/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 2, 2026 section_ids: steps: Steps provider_configuration: Provider configuration authorization-methods: Authorization methods body-option: Body option payload_format: Payload format apns-json-payload-example: APNs JSON payload example fcm-json-payload-example: FCM JSON payload example hms-json-payload-example: HMS JSON payload example --- # Configuring a custom push notification provider (early access) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This feature is now available for early access in PingOne. Early access features and APIs are provided for preview purposes only and might change in the final version. Learn more about early access in [PingOne Early Access Features](p1_early_access_features.html) and [Managing opt-ins for early access features in PingOne](../settings/p1_managing_opt_ins_for_ea_features.html). | Use the **Senders** page to configure a custom push notification provider for PingOne MFA. ## Steps 1. In the PingOne admin console, go to **Settings > Senders**. 2. Click **+**, in the **Sender Type** list, select **Push**, and then click **Next**. **Provider Type** is set with the value **Custom Provider**. 3. On the **Provider Configuration** page, enter the values from the [Provider configuration table](#provider_configuration). 4. Under **Body**, if you choose **Form**, click **+ Add Key, Value** for each key-value pair that you want to enter. 5. Under **Headers**, click **+ Add Header** to add any additional headers required by your push gateway. When you select **Body > Form** the header key value pair is prepopulated with `content-type` `application/x-www-form-urlencoded`. When you select **Raw**, the header key-value pair is prepopulated with `content-type` `application/json`. You can edit or remove this default header as needed. 6. Click **Save**. You can configure up to three custom push providers, which are always available for use. To use a custom push provider, you must select it in the native application configuration. Learn more in [Editing an application - Native](../applications/p1_edit_application_native.html). Learn how to use the Push Delivery Settings API to create a custom push sender in [Push Delivery Settings](https://developer.pingidentity.com/pingone-api-ea/platform/early-access/push-delivery-settings.html) in the PingOne developer early access documentation. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * When using a custom provider, if there are repeated errors within a short period or long delays before responses from the provider, PingOne assumes that there is an underlying issue and temporarily activates a circuit breaker, suspending notification attempts for that provider. * Custom providers use a five-second connect timeout and a three-second read timeout. | ## Provider configuration | Field | Type | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Provider Name** | Mandatory | A meaningful name for your push provider. It prepopulates to **Custom Provider**. | | **Authorization** | Mandatory | The authorization method, learn more in [Authorization methods](#authorization_methods). | | **Type** | Fixed | The HTTP method used for push notification requests to the associated endpoint. It's always **POST** for push providers. | | **URL** | Mandatory | The endpoint on your custom push gateway that receives push notification requests. | | **Body** | Mandatory | Defines the request body format sent to your gateway. Learn more about **Body** formats in [Body option](#body_option).The body must include the `${push-data}` variable, which PingOne replaces with the full push payload object at runtime. Learn more in [Payload format](#payload_format). You can optionally include the `${push-provider}` variable to identify the push provider type, such as `APNS`, `FCM`, or `HMS`. | | **Headers** | Optional | Any additional HTTP headers your gateway requires. | ## Authorization methods | []()Authorization method | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Basic** | Enter the **username** and **password** for the provider account. Once set, you can click **Change Account** to enter a new password for the custom provider account. | | **Bearer** | Set a static bearer token for the provider account. | | **OAuth2 – Client Credentials** | Use an authorization server that issues access tokens based on client ID and client secret. | | **Custom Header** | Use a custom HTTP header name and value for authorization. | ## Body option | []()Body option | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Form** | The notification request body is in the form of key and value pairs. | | **Raw** | The notification request body in a raw payload. Enter the notification request as JSON text according to your gateway's expectation. For instance, `{ "pushData": "${push-data}", "pushType": "${push-provider}" }` | ## Payload format PingOne sends the `${push-data}` payload to your configured gateway endpoint, which forwards it to the appropriate service, either **Apple Push Notification service (APNs)**, **Firebase Cloud Messaging (FCM)**, or **Huawei Mobile Services (HMS)**. The PingOne payload uses a modified payload format. Your gateway must map it to the format that the target service expects before forwarding. The payload contains fields shared by both services, and fields specific to that service: | Field | Service | Description | | ------------------------ | ------- | ----------------------------------------------------------------------------- | | `priority` | All | Delivery priority. | | `dryRun` | All | When `true`, the request is validated without being delivered. | | `ttl` | All | Time-to-live in seconds. | | `pushToken` | All | Device token identifying the target device. | | `packageName` | FCM HMS | Application package name. | | `collapseKey` | FCM | An identifier used for grouping messages. | | `bundleId` | APNs | iOS application bundle identifier. | | `pushType` | APNs | APNs push type, like `alert` or `background`. | | `badgeNumber` | APNs | Badge count to display on the app icon. | | `contentAvailable` | APNs | When `true`, wakes the app in the background to download new content. | | `categoryName` | APNs | Action category registered in the app for actionable notifications. | | `localizedAlertKey` | APNs | Localization key for the alert body string. | | `localizedAlertTitleKey` | APNs | Localization key for the alert title string. | | `alertTitle` | APNs | Fallback alert title. | | `alertBody` | APNs | Fallback alert body text. | | `soundFileName` | APNs | Sound file to play on delivery. | | `interruptionLevel` | APNs | iOS 15+ interruption level. | | `mutableContent` | APNs | Allows a Notification Service Extension to modify the payload before display. | | `data` | All | PingOne-populated custom key-value pairs delivered to the application. | ### APNs JSON payload example ```json { "priority": "high", "dryRun": false, "ttl": 3600, "pushToken": "", "bundleId": "com.example.yourapp", "pushType": "alert", "badgeNumber": 1, "contentAvailable": true, "categoryName": "auth_request", "localizedAlertKey": "AUTH_ALERT", "localizedAlertTitleKey": "AUTH_TITLE", "alertTitle": "Authentication Request", "alertBody": "Tap to approve your sign-in.", "soundFileName": "default", "interruptionLevel": "time-sensitive", "mutableContent": true, "data": { "key1": "value1", "key2": "value2" } } ``` ### FCM JSON payload example ```json { "priority": "high", "dryRun": false, "ttl": 0, "pushToken": "", "packageName": "com.example.yourapp", "data": { "key1": "value1", "key2": "value2" } } ``` ## HMS JSON payload example ```json { "priority": "high", "dryRun": false, "ttl": 0, "pushToken": "your_hms_token", "data": { "key1": "value1", "key2": "value2" }, "packageName": "com.example.yourapp", "collapseKey": 0 } ```