About the Okta Expression Language

Event hooks now include filtering support and a new creation flow. These are Beta features. See Beta Programs. To provide feedback on event hook filtering, complete the Feedback form.

Use Okta Expression Language (EL) expressions to identify only certain events that trigger Okta event hooks. When creating or modifying an event hook, you can use Okta EL expressions to:

• Define a filter to allow a subset of events that are triggered by an event hook.

• Reduce the noise to the external web service handling your event hook.

For complete details on Okta EL, see Okta Expression Language Overview.

Configuration information

• Ensure that your expression evaluates to a Boolean when defining a filter for your event hook.

• Start with simple expressions and gradually add conditions. This approach helps to make sure that your expression works as expected.

Use

• eq to denote the Equality operator.
• ne to denote the Inequality operator.
• && to denote the And operator.
• || to denote the Or operator.

Define group conditions

Use the Okta EL to define a list of groups that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include groups or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a group called: Sales:

event.target.?[type eq 'UserGroup' && displayName eq 'Sales'].size()> 0

...
   "target": [
      {
        "id": "00gsnc3qy7Uy6JZfy0h7",
        "type": "UserGroup",
        "alternateId": "unknown",
        "displayName": "Sales"
      }
    ],
...

Use the following event types with group conditions:

• group.user_membership.add

• group.user_membership.remove

• group.lifecycle.create

• group.lifecycle.delete

• group.profile.update

• group.privilege.revoke

• group.privilege.grant

• system.import.group.create

• system.import.group.delete

Sample expressions

Define application conditions

Use the Okta EL to define a list of applications that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a Bookmark application named My COMPANY Bookmark App:

event.target.?[type eq 'AppInstance' && alternateId eq 'My COMPANY Bookmark App'].size()> 0

...
     "target": [
        {
          "id": "0oat26meilfdn0Em90h7",
          "type": "AppInstance",
          "alternateId": "MY COMPANY Bookmark App",
          "displayName": "Bookmark App"
        },
...

Use the following event types with application conditions:

• application.lifecycle.create

• application.lifecycle.update

• application.lifecycle.delete

• application.lifecycle.activate

• application.lifecycle.deactivate

• application.user_membership.add

• application.user_membership.remove

• application.user_membership.change_password

• application.provision.user.sync

• app.oauth2.as.consent.grant

Sample expressions

Define user profile conditions

Use the Okta EL to define a list of user profile attributes that activate an event hook. Ensure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a user whose email has been updated:

event.debugData.changedAttributes.contains('email')

..
     "debugContext": {
        "debugData": {
          "requestId": "XyMjlc1OvvWkZPMA7QazbwAAFIs",
          "threatSuspected": "false",
          "requestUri": "/api/v1/users/00ut27as6fbC0K3rS0h7",
          "changedAttributes": "email",
          "targetEventHookIds": "whot1dekaabE2suVh0h7",
          "url": "/api/v1/users/00ut27as6fbC0K3rS0h7?"
        }
      },
...

The following represents the most common event type for profile conditions:

• user.account.update_profile

Sample expressions

Define login conditions

Use the Okta EL to define specific sign in conditions that activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

This list provides available outcome options: SUCCESS, FAILURE, SKIPPED, UNKNOWN, CHALLENGE, DENY.

The following example uses the Okta EL to activate an event hook for a successful user sign in:

event.outcome.result eq'SUCCESS'

The following example uses the Okta EL to activate an event hook for a failed user sign in:

event.outcome.result eq'FAILURE'

The following represents the most common event type for a sign in condition:

• user.session.start

Sample expressions

Define MFA factor conditions

Use the Okta EL to define a list of MFA factors that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook when a security question is set up as an MFA Factor:

event.outcome.reason.contains( 'SECURITY_QUESTION')

Use the following event types with factor conditions:

• user.mfa.factor.activate

• user.mfa.factor.deactivate

Sample expressions

Related topics

About event hooks

Create an event hook