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.

Subscriptions data model

Property Type Require? Mutable? Description

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

Required

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.headers

String[]

Required

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.

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.