Creating a notification webhook

Notification webhooks are external API calls that you use to send data to a third party when specific events occur.

About this task

You can configure the request URL of the external API that you want to start and add any headers of parameters that are required for starting the request URL. For information about event payloads, see Event types and payloads.

Within the webhook configuration JSON, a property notification exists. This property is a nested JSON object that contains all of the notification-specific configuration options. The interests property is defined within this notification object. When an event is raised, it is checked against each element in the interests property. If any element in the interests property evaluates to a match, the event is sent to the webhook destination. Interests are checked in order, so in high-performance use cases, put the broadest match first.

An interest consists of two fields, a friendly name and a list of clauses. These clauses decide whether the interest is a match or not. The clauses are joined with an AND operation, and only if they all match the interest is satisfied. A clause consists of three fields:

  • key
  • value
  • operation - valid values are include and exclude.
The key is a JSON property name and is used to indicate where in the event to determine whether this clause matches. The key can be used to evaluate top-level keys or keys within the data object of an event. When it references the data object, JSON dot notation is used, for example data.action. The value is the expected value of the field that is being inspected. The operation indicates whether a match on this clause causes the event to be included or excluded.

For example, when authentication events are the key interest, but you want to filter out authentications that occur through federation, use these clauses:

  • Key: event_type, Value: authentication, Operation: include
  • Key: data.subtype, Value: federation, Operation: exclude

These clauses become the logical evaluation:

event_type IS authentication AND data.subtype IS NOT federation.

For more information, see Notification webhooks.

Procedure

  1. Navigate to Integrations > Notification webhooks.
  2. Click Create webhook.
  3. Provide a name for the webhook.
    You can also specify an owner and email contact information.
  4. Specify one or more request URLs for the API.
  5. Select the type of authentication.
    Basic
    Specify the username and password.
    Header
    Specify the header name and authentication secret. If the secret is case-sensitive, select the Sensitive checkbox.
    None
    No authentication information is needed.
    OAuth
    Specify the token endpoint, select whether the client secret is post or basic, enter the client ID and secret.
    Note: Client post indicates that the secret is stored as an attribute. Client basic indicates that the secret is stored in the header.
    JSON Web Token (JWT)
    Specify the HTTP header value, Sub claim, Maximum valid lifetime of the JWT, and Signing algorithm. If you want, you can also specify a JWT header value prefix, a JWT header keys and claim names.
    Mutual TLS (mTLS)
    Specify the MTLS certificate label.
  6. Optional: Enter any custom headers and values.
  7. Optional: Enable Dead letters.
    The Dead letters feature records unsuccessful notifications.
    1. Enable Automatically attempt dead letter reconciliation and select the attempt reconciliation interval.
      You can specify to resend the notification every 5, 15, or 30 minutes.
  8. Click Next.
  9. Specify the event subscriptions for your webhook.
    When any of the events that you specify occur, a notification is triggered for the webhook. Select a predefined event or add a custom event. You must specify at least one event.
  10. Optional: Click Predefined events.
    1. Select the checkbox for one or more of the pre-defined events.
      • All authentication events
      • Failed authentication events
      • User profile modified
      • User profile created
      The events that you choose are listed in the Details pane for the Selected events.
    2. Click Add.
      You are returned to the Event subscription page and the events are listed in the Event configuration section.
  11. Optional: Click Add custom event.
    1. Provide a name for the event.
      You can also specify a description of the event.
    2. Specify the interests that trigger the event.
      Events are a property and value pair that must evaluate as true to trigger the event.
    3. Specify whether to include or exclude the interest.
      You might specify event_type authentication include and user.type admin exclude to trigger the webhook on every authentication event that isn't from and admin.
    4. Optional: Specify more interests.
  12. Click Add.
    You are returned to the Event subscription page and the event is listed in the Event configuration section.
  13. Optional: Add more custom events.
  14. Click Create.
    The webhook is listed on the Notification webhooks page and the webhook is displayed.
  15. Optional: Modify the events of the webhook.
    1. Add more custom and predefined events.
    2. Edit the events
      1. Select the event that you want to modify and click the pencil icon Edit icon.
      2. You can change the name or description. You can add or modify the interests.
      3. Click Update.
    3. To remove an event, select it and click the Remove icon Subtraction sign inside a circle.
  16. Optional: Modify the connection details.
    1. Select Connection details.
    2. Modify all the settings except for Purpose and Integration version.
    3. Test the connection.
    4. View the health status.
    5. Delete the webhook.
  17. If you made any changes, click Save changes.
  18. Click Notification webhooks to return to the Notification webhooks page.