Event hooks

The topics on this page are for tenants created on or after January 12, 2023. Learn more in Event hooks migration FAQ.

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

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, learn more in Scripting tips.

Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume Advanced Identity Cloud logs.

Ping Identity recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Advanced Identity Cloud tenant environments.

Create a new event hook

In the Advanced 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. Advanced 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 Advanced Identity Cloud tenant.

PingOne Advanced Identity Cloud

Event hooks

Create a new event hook

Scripting tips

Use a variable in an event hook script

Use an ESV in an event hook script