PingOne Platform APIs

Subscriptions (webhooks)

The subscription service provides an interface for third-party auditing tools to subscribe to and consume PingOne audit activity events. The service listens for translated audit activities as the source of events and transmits messages about these events to the subscribing audit application.

Use only IPv4 addresses for webhooks. IPv6 addresses are not fully-supported.

For more information about subscriptions (webhooks), refer to Webhooks in the PingOne Admin Guide.

If the webhook target is offline, PingOne continues to retry and queue up all matching events. If the webhook target is down for longer than 7 days, PingOne starts to lose events.

The webhook continues to retry the current event until a 200 response is returned. It doesn’t move on to the next event until a 200 response has returned or the event has expired from Kafka.

This service includes a property to designate whether to verify TLS certificates that establish the Secure Sockets Layer (SSL) protocol to the HTTP endpoint. For certificate verification, the following behaviors apply:

  1. If the verifyTlsCertificates property is set to false, then all certificates are trusted.

  2. If the verifyTlsCertificates property is set to true, and the certificate presented by the HTTPS endpoint has been signed by a default CA, then PingOne trusts it automatically.

  3. If the verifyTlsCertificates property is set to true, and the HTTPS server’s certificate was signed by a CA that is not trusted by default, then that CA’s certificate must be uploaded to the certificate service (prior to creating a subscription) with a usage type of SSL/TLS to indicate that certificates signed by this CA are trusted by the PingOne platform for outbound SSL/TLS connections.

  4. If the verifyTlsCertificates property is set to true, and the HTTPS server’s certificate is self-signed, then that certificate itself must be uploaded through the PingOne certificate service prior to creating a subscription.

For more information about certificates, refer to Certificate management.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Subscriptions data model

Property Type Require? Mutable Description

connectionDetails

Object

Optional

Mutable

Contains the outbound request headers and URI for the event messages. Similar to httpEndpoint, but not HTTPS-specific.

connectionDetails.headers

String[]

Optional

Mutable

The headers applied to the outbound request (for example: "Authorization": "Basic username:password"). The purpose of these headers is to authenticate the PingOne service, ensuring that the information from PingOne is from a trusted source. Similar to httpEndpoint.headers, but not HTTPS-specific.

connectionDetails.url

String

Required

Mutable

A string that specifies a valid a URI to which event messages are sent. Similar to httpEndpoint.url, but not HTTPS-specific.

createdAt

Date

N/A

Read-only

The date and time at which the subscription resource was created (ISO 8601 format).

enabled

Boolean

Required

Mutable

Indicates whether a created or updated subscription should be active or suspended. A suspended state ("enabled":false) accumulates all matched events, but these events are not delivered until the subscription becomes active again ("enabled":true). For suspended subscriptions, events accumulate for a maximum of two weeks. Events older than two weeks are deleted. Restarted subscriptions receive the saved events (up to two weeks from the restart date).

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the subscription.

filterOptions.includedActionTypes

String[]

Required

Mutable

A non-empty array that specifies the list of audit events that should be matched for the subscription. Refer to Audit Reporting Events for valid audit events.

filterOptions.includedApplications

String[]

Optional

Mutable

The list of applications (by ID) whose events are monitored by the subscription (maximum of 10 IDs in the array). If a list of applications is not provided, events are monitored for all applications in the environment.

filterOptions.includedPopulations

String[]

Optional

Mutable

The list of populations (by ID) whose events are monitored by the subscription (maximum of 10 IDs in the array). This property matches events for users in the specified populations, as opposed to events generated in which the user in one of the populations is the actor.

filterOptions.includedTags

String[]

Optional

Mutable

The tags that events must have to be monitored by the subscription. If tags are not specified, all events are monitored. Currently, the available tags are:

  • adminIdentityEvent. Identifies the event as the action of an administrator on other administrators.

filterOptions.ipAddressExposed

Boolean

Optional

Mutable

Whether the IP address of an actor should be present in the source section of the event.

filterOptions.userAgentExposed

Boolean

Optional

Mutable

Whether the User-Agent HTTP header of an event should be present in the source section of the event.

format

String

Optional

Mutable

One of the supported subscription formats. Options are:

  • ACTIVITY. Ping Activity Format. A generic JSON format. Use this if your destination doesn’t support Splunk or New Relic formats.

  • SPLUNK. A Splunk-friendly format.

  • NEWRELIC. A New Relic-friendly format.

httpEndpoint

Object

Optional

Mutable

Contains the outbound request headers and URL for the event messages.

httpEndpoint.headers

String[]

Optional

Mutable

The headers applied to the outbound request (for example: "Authorization": "Basic username:password"). The purpose of these headers is for the HTTPS endpoint to authenticate the PingOne service, ensuring that the information from PingOne is from a trusted source.

httpEndpoint.url

String

Required

Mutable

A string that specifies a valid HTTPS URL to which event messages are sent.

id

String

N/A

Read-only

The resource’s unique identifier.

name

String

Required

Mutable

The subscription name.

payloadOptions.maximumPayloadLimit.type

String

Optional

Mutable

The type of payload to use for limiting subscriptions. You can limit by EVENTS_PER_PAYLOAD or KB_PER_PAYLOAD.

payloadOptions.maximumPayloadLimit.size

Integer

Optional

Mutable

The maximum size of the payload based on payloadOptions.maximumPayloadLimit.type. For EVENTS_PER_PAYLOAD this can be from 1 to 500 events (defaults to 500). For KB_PER_PAYLOAD this can be from 1 to 4096 kilobytes.

payloadOptions.payloadFormat.https.format

String

Optional

Mutable

The payload format. This can be either JSON_ARRAY or ND_JSON.

payloadOptions.payloadFormat.https.prettyPrint.

Boolean

Optional

Mutable

Only applicable when payloadOptions.payloadFormat.format is JSON_ARRAY. Pretty-print is enabled when true.

payloadOptions.payloadFormat.tcp.format

String

Optional

Mutable

The payload format. This can be either JSON_DOC or RFC_LOGLINE.

payloadOptions.payloadFormat.tcp.additionalAttributes

Object

Optional

Mutable

Applicable only when payloadOptions.payloadFormat.tcp.format is set to RFC_LOGLINE. The attributes are specified as key-value pairs.

protocol

String

Optional

Mutable

This can be either HTTPS or TCP_IP.

tlsClientAuthKeyPair.id

String

Optional

Mutable

The ID of a key to be used for outbound mutual TLS (mTLS) authentication. This key is used as a client credential to authenticate the webhook. The key must have a usageType of OUTBOUND_MTLS. Refer to Certificate management for information on creating a key. If this property is set, verifyTlsCertificates must be set to true.

updatedAt

Date

N/A

Read-only

The date and time at which the subscription resource was last updated (ISO 8601 format).

verifyTlsCertificates

Boolean

Required

Mutable

Indicates whether a certificates should be verified. If this property’s value is set to false, then all certificates are trusted. (Setting this property’s value to false introduces a security risk.) This value must be set to true if tlsClientAuthKeyPair.id is set.

Subscription Events

You can subscribe to any of the audit events listed in Audit Reporting Events.

The audit events triggered by your subscription requests are also in the Audit Report Events list: SUBSCRIPTION.CREATED, SUBSCRIPTION.UPDATED, and SUBSCRIPTION.DELETED.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

The request could not be completed. You do not have access to this resource.

404

The requested resource was not found.

Subscriptions errors

In addition to the general error codes, subscriptions operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT request omits a required request body property (name, filterOptions, filterOptions.includedActionTypes, enabled, or verifyTlsCertificates, and httpEndpoint.url for HTTPS subscriptions), or filterOptions.includedActionTypes is an empty array, or the webhook URL is not a valid HTTPS URL (or, for TCP_IP subscriptions, tcp://)

Details: field is expected to be present for an omitted name, filterOptions, enabled, verifyTlsCertificates, or httpEndpoint.url, at least one action type is expected to be present for an empty filterOptions.includedActionTypes, or is expected to be a valid URL with https protocol and no illegal characters for an invalid webhook URL (or is expected to be a valid URL with tcp protocol and no illegal characters for TCP_IP subscriptions), for example Validation Error : [filterOptions field is expected to be present]

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: A resource with the specified name already exists.

When and details

When: A POST request creates a subscription whose name duplicates another subscription in the environment, or a PUT request renames a subscription to a name that another subscription in the environment already has

Details: Environment id=<environmentId> already has the subscription with a name=<name>

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request references a population ID in filterOptions.includedPopulations or an application ID in filterOptions.includedApplications that does not exist in the environment

Details: The population or application client error message returned by the backing service.

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT request sets filterOptions.includedActionTypes to an action type that is not in the service’s supported list (for example, TRUSTED_ISSUER.CREATED, SSO_COOKIE_SETTINGS.UPDATED, or an external IDP account-linking attribute event)

Details: Specified '<actionType>' action type is not supported. Supported action types are: <supported types>, for example Validation Error : [filterOptions.includedActionTypes Specified 'INVALID.ACTION_TYPE' action type is not supported. Supported action types are: <supported types>]

400

INVALID_REQUEST

None

Message: The request could not be completed. The request was malformed or invalid. (request body) or the feature-gate message, such as Invalid request, protocol is not supported, Invalid request, httpEndpoint is expected to be present, Invalid request, connectionDetails is not supported, or Invalid request, TCP payload options are not supported

When and details

When: The request body cannot be deserialized, or the subscription uses TCP‑only fields when the TCP destination feature is not enabled for the environment (protocol set, connectionDetails set, payloadOptions.payloadFormat.tcp set, or httpEndpoint omitted)

Details: None. (The feature-gate messages replace the default message; the response still carries the INVALID_REQUEST code with no detail.)

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the subscriptions:read:subscription permission (GET operations), subscriptions:create:subscription (POST), subscriptions:test:subscription (the test-subscription operation), subscriptions:update:subscription (PUT), or subscriptions:delete:subscription (DELETE)

Details: None.

403

REQUEST_LIMITED

None

Message: Exceeded the limit of 50 subscriptions for envId: <environmentId>

When and details

When: A POST create-subscription request would exceed the environment limit of 50 non-retired subscriptions

Details: None.

403

REQUEST_FAILED

None

Message: Test connection feature is not enabled

When and details

When: A test-subscription request is made for an environment that does not have the webhook test-connection feature enabled

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, DELETE, or test-subscription request specifies a subscription ID that does not exist in the specified environment

Details: None.