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 and Managing opt-ins for early access features in PingOne.

Use the Senders page to configure a custom push notification provider for PingOne MFA.

Steps

In the PingOne admin console, go to Settings > Senders.
Click +, in the Sender Type list, select Push, and then click Next.

Provider Type is set with the value Custom Provider.
On the Provider Configuration page, enter the values from the Provider configuration table.
Under Body, if you choose Form, click + Add Key, Value for each key-value pair that you want to enter.
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.
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.

Learn how to use the Push Delivery Settings API to create a custom push sender in Push Delivery Settings 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

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.
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. The body must include the `${push-data}` variable, which PingOne replaces with the full push payload object at runtime. Learn more in 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.

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.

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.

The body must include the ${push-data} variable, which PingOne replaces with the full push payload object at runtime. Learn more in 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.

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

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}" }`

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

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.

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

{
  "priority": "high",
  "dryRun": false,
  "ttl": 3600,
  "pushToken": "<your_apns_token>",
  "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

{
  "priority": "high",
  "dryRun": false,
  "ttl": 0,
  "pushToken": "<your_fcm_token>",
  "packageName": "com.example.yourapp",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

HMS JSON payload example

{
  "priority": "high",
  "dryRun": false,
  "ttl": 0,
  "pushToken": "your_hms_token",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "packageName": "com.example.yourapp",
  "collapseKey": 0
}