--- title: Subscriptions (webhooks) description: 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. component: pingone-api page_id: pingone-api:platform:subscriptions-webhooks canonical_url: https://developer.pingidentity.com/pingone-api/platform/subscriptions-webhooks.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service subscriptions-data-model: Subscriptions data model subscription-events: Subscription Events response-codes: Response codes --- # 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](https://docs.pingidentity.com/pingone/integrations/p1_webhooks.html) 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](certificate-management.html). | ## 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](reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.html) 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](reference/audit-reporting-events.html) 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](certificate-management.html) 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](reference/audit-reporting-events.html). 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. |