PingOne

Creating or editing a webhook (early access)

You can create a webhook to monitor events in PingOne.

Before you begin

Before setting up webhooks, ensure your endpoint meets the required protocol standards. Webhooks deliver events using a standard HTTPS POST request with a JSON payload, so your endpoint must be an HTTPS server that can receive and process these requests. The system doesn’t support raw TCP sockets, such as those used by syslog daemons. Directing a webhook to a non-HTTPS listener results in delivery failures.

Each webhook request contains a single JSON document with a batch of up to 500 events. These events are included as an array within the payload. The system doesn’t use line-delimited JSON or send individual event payloads per request.

Steps

  1. In the PingOne admin console, go to Integrations > Webhooks.

  2. Do one of the following:

    • To create a new webhook, click the icon.

    • To edit an existing webhook, browse or search for the webhook you want to edit, click it to open the details panel, then click the Pencil icon () on the applicable tab.

      If you’re editing an existing webhook, go to the applicable step for the information you’re changing.

  3. In the Name field, enter a descriptive name for the connection.

  4. In the Destination URL field, enter the IP address or host name of the application that you want to send data to.

    IPv6 addresses aren’t supported.

  5. (Optional) Enter the Certificates information.

    Adding a certificate can ensure that the webhook connection is secure.

    • If there are certificates listed in the Trusted PingOne Certificates field, click the applicable certificate and enter an expiration date.

      You can also add a new certificate by clicking Upload New Certificate.

    • Allow TLS connection with untrusted certificates: Select this checkbox to allow a certificate that’s not from a certificate authority (CA). PingOne certificates, and all certificates signed by the default CAs, are trusted. This option is typically used for testing. Learn more in Certificates and key pairs.

    • TLS Client Authentication Key: Click a key to enable mutual TLS (mTLS). The key is used as a client credential to authenticate the webhook and must have a usage type of Outbound mTLS. Learn more in Adding a certificate and key pair.

      To use a TLS client authentication key, you must disable the Allow TLS connection with untrusted certificates setting.

    • If you’re editing an existing webhook and want to delete a certificate, click the webhook and click the to the right of the screen on the Overview tab. In the Certificates section, find the certificate you want to delete and click the Delete icon.

  6. (Optional) Enter the Headers information.

    • Basic authentication: Enter a username and password for the destination system.

    • Custom HTTP headers: Click Add Custom HTTP Headers and enter the information for the Key and Value fields.

      For example, you can define a custom authorization header with a token instead of using basic authentication. This is the common method for modern security information and event management (SIEM) systems, such as Splunk and Sumo Logic.

  7. Enter the Payload Format information.

    • Event Schema: The format of the activity data. Choose the format that is most easily consumed by your management system:

      • Splunk: A Splunk-friendly format.

      • Ping Activity Format: Use this format if the destination can’t directly accept the Splunk or New Relic formats. It’s a versatile, generic JSON format, which is the same format used by the PingOne API for accessing event data using Audit Activities. Learn more in the subscription action types table in Subscriptions (webhooks) in the PingOne API documentation.

      • New Relic: A New Relic-friendly format.

    • Payload Limit: Select one of two options to limit the amount of data included in the webhook payload by size in KB or by number of events.

      Some SIEM tools limit the amount of data that the receiving system can accept from a single payload. Limiting the size of the payload when you configure your webhooks can ensure that the destination system doesn’t reject the message from PingOne and cause delivery errors.

      If you don’t specify an option here, the default maximum is 500 events per payload.

      • Select Limit by Events or Limit by Size.

        • If you select Limit by Events, then enter a Maximum Payload Limit (1-500). This sets the maximum number of events returned in each payload.

        • If you select Limit by Size, then enter a Maximum Payload Size (1-4096). This sets the maximum KB size of each payload.

          Performance is better with larger payloads. If you’re limiting by events, enter 250 or higher. If you’re limiting by size, enter 500 KB or higher.

          Regardless of the payload event or size settings, at least one event will always be in the payload, and events are held no more than 2 seconds before sending.

    • Specify whether to include the IP address and User Agent strings in the report. Because IP addresses and User Agent strings can be considered sensitive data, you must manually select these options to include them in the report.

      • Include IP address: Include the end user’s IP address in the report. IP addresses are the client’s IP address as it appears to the PingOne services. In some cases, this value is a proxy address rather than the actual client device address.

      • Include User Agent: Include the User Agent String in the report. User Agent Strings are included if PingOne interacts with the user client when the client provides the string. The recorded value is exactly what was presented to PingOne by the client.

  8. Click Next.

  9. In the Event Types section, click to select the events to monitor with this webhook.

    There are two tabs in this section:

    • All Event types: On this tab, select the types of events to monitor, such as user created, user deleted, and so on. When you click a category of event types, all of the event types in that subset are automatically selected. Expanding the category using the dropdown arrow by each event type will allow you to choose from the subset of events.

    • Selected: Click this tab to view what’s currently selected. You can find a complete list of events logged in PingOne in Audit Reporting Events in the PingOne API documentation.

    You can also search for events using the search bar provided in the Event Types section.

  10. In the Additional Conditions section, narrow the criteria for the events to monitor with this webhook.

    • Tags: Specify a tag to monitor.

      Admin Identity Event: An action taken by an administrator or API client on another administrator user, such as:

      • Creating or deleting an administrator user

      • Enabling or disabling an administrator user

      • Adding or removing roles from an administrator user

      • Changing a password for an administrator user

      • Changing username or email address for an administrator user

      • Enabling or disabling MFA for an administrator user

      • Pairing a new MFA device for an administrator user

      • Adding or removing linked accounts for an administrator user

    • Applications: Specify the applications in your PingOne environment that you want to monitor. You can choose up to 10 applications.

    • Populations: Specify the populations in your PingOne environment that you want to monitor. You can choose up to 10 populations.

      For each filter, such as events, applications, or populations, the expression evaluates to true if any of the criteria are met (Boolean OR).

      For multiple filters, the expression evaluates to true if all of the criteria are met (Boolean AND).

  11. Click Save.

  12. The webhook is enabled automatically, with the toggle at the top of the details panel moved to right (blue).

    You can disable the webhook by clicking the toggle to the left (gray).