Event hooks

Overview

The topics on this page are for tenants created or migrated to on or after January 12, 2023.

Event hooks let you trigger scripts during various stages of the lifecycle of users, roles, assignments, organizations, groups^[1] and applications^[2].

You can trigger scripts when one of these identity objects is created, updated, retrieved, deleted, validated, or stored in the repository. You can also trigger a script when a change to an identity object triggers an implicit synchronization operation.

Post-action scripts let you manipulate identity objects after they are created, updated, or deleted.

For some links to help with writing scripts for event hooks, and a few examples, see Scripting tips.

Create a new event hook

In the Identity Cloud admin UI, go to Realm > Event Hooks.
On the Event Hooks page, click + New Event Hook.
On the New Event Hook page, enter event hook details:
1. Enter the Name for the event hook.
2. (Optional) Enter a Description for the event hook.
3. Identify a condition that will trigger a script to run. In the Condition field:
  - Select an identity object type—a user, role, assignment, organization, group, or application— from the Object Name drop-down list.
  - Select an event type from the Event drop-down list.
    Note that event types that have already been configured in event hooks do not appear in the drop-down list. Identity Cloud lets you configure exactly one event hook per condition.
4. Specify a script to run when the event hook is triggered. Either:
  Type JavaScript code into the Script field.
  
  Or, click the Upload File toggle, and then click Browse. Then, select the file that contains the JavaScript code that will run when the event hook is triggered.
5. (Optional) Enter variables to be passed to the event hook’s script. Either:
  - Click + Add Variables, and then enter variable names and values in the Variables > Name and Variables > Value fields.
  - Or, click the JSON toggle, and then type JSON-formatted values into the Variables field.
Click Save.

Scripting tips

The following links contain general information to help you write scripts triggered by event hooks:

The sections that follow contain code snippets that might be helpful when you start developing your own event hook scripts.

Use a variable in an event hook script

This example adds a prefix to a user’s last name (sn attribute) in the user creation event hook.

Add a variable named myCompany to the event hook, and set its value to the desired prefix.
Specify a script similar to the following in the event hook:
```
object.sn = myCompany + "-" + object.sn;
```

Use an ESV in an event hook script

This example sets the value of a user’s Description attribute to the value of an ESV in the user creation event hook.

Either specify the ESV in a variable:
1. Add a variable named myDescriptionESVValue to the event hook.
2. Set the variable’s value to &{esv.myDescription}.
3. Specify a script similar to the following in the event hook:
  object.description = myDescriptionESVValue;

Or, use the identityServer object to get the ESV value:

object.description = identityServer.getProperty("esv.myDescription")

1. Event hooks are available for groups if you have enabled the groups feature in your Identity Cloud tenant.

2. Event hooks are available for applications if the advanced application management features are available in your Identity Cloud tenant.