Okta Expression Language and event hooks

Early Access release. See Enable self-service features.

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 perform the following tasks:

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

Supported Filter Fields

Event hooks can only filter events based on the data in the following fields:

Operators

• eq denotes the Equality operator.

• ne denotes the Inequality operator.

• && denotes the And operator.

• || denotes 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 sign-in 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:

event.outcome.result eq'SUCCESS'

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

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

Verify an event hook

Event hooks

Preview an event hook