Construct a filter
Before creating the webhooks subscription in Identity Cloud, you may need to construct a filter. By default, webhooks notifications are triggered when the event occurs in ANY of your Identity Cloud applications and entity types. And the entityUpdated event will trigger based on an update to ANY attribute in the user record.
A webhooks filter is an optional configuration that will limit the notifications sent to your endpoint to only those you care about. You can filter webhooks based on any of the data points from the webhook payload. The following are the most useful:
- Application ID
- Entity Type
- Client ID
- Schema Attribute Name (Only applies to
entityUpdatedevents)
Note that this is a server-side filter that permanently discards any events not matching the filter criteria before the event notification is sent to you. You can also apply filtering on your end as part of your webhook receiver processing. It is up to you whether you use this server-side filter, your own filter, or a mix of both.
The actual filter itself is a JSON object that specifies which event to apply the filter to and which data points and values to filter on.
Your webhooks filter will look something like this:
"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
"entityUpdated": {
"properties": {
"captureApplicationId": {
"const": "aabc1de2f3ghi4jklm5n67opq8"
},
"entityType": {
"const": "user"
},
"attributes": {
"contains": {
"enum": [
"givenName",
"familyName",
"primaryAddress.city"
]
}
}
}
}
}
}In human terms, the above filter says that when a user record is updated, send a notification ONLY IF:
- The user record is associated with my Identity Cloud application whose ID is aabc1de2f3ghi4jklm5n67opq8 AND
- The user record resides in the user entity type AND
- The piece of data updated was given name, family name, or city
Migrating from webhooks v2 to v3? For a more seamless transition, make sure to construct a filter that mimics the current behavior of your v2 webhooks. If you don’t remember exactly which attributes you currently filter on, for example, reach out to your Identity Cloud representative and we can look it up for you.
Moving forward with webhooks v3, you’ll always have direct access to this configuration and can view or edit it on the fly without involving an Identity Cloud team member.
1. Build-A-Filter
Fill out the fields below to build your basic webhooks filter.
You can refine or expand this filter as needed in the next step. Using the Build-A-Filter will generate a working filter configuration to get you started.
| Select the event to apply this filter to. |
|---|
This event must match one of the following: |
| Which Identity Cloud application are you configuring this webhook for? (E.g. I only want to receive webhooks for MyCompany EU Prod.) |
|---|
|
Please enter the application ID below.
Find It
You can find the Application ID in the Identity Cloud Console:
|
| Would you like to filter on entity type? (E.g. I have multiple entity types in the application above, but I only want to receive webhooks for users residing in the user_patients entity type.) |
|---|
|
If so, please enter the entity type name below. If not, leave it blank.
Find It
You can find the Entity Type name in the Identity Cloud Console:
|
| Would you like to filter on client ID? (E.g. I have multiple properties in the application above, but I only want to receive webhooks for users that interact with My Mobile App Login Client.) |
|---|
|
If so, please enter the client ID below. If not, leave it blank.
Find It
You can find the Client ID in the Identity Cloud Console:
|
| Would you like to filter on user profile data attributes? (E.g. There are many data attributes that could be updated in the user record, but I only want to receive webhooks when the user’s email address or phone number are updated.) |
|---|
| If so, please enter the attributes below. If not, leave it blank. This must be formatted as a comma-separated list with quotes around each attribute name, as seen in the examples below. Example: "email","mobileNumber","consents.marketing"Example for just one attribute: "email"Tip! To filter on a plural attribute, make sure to include the parent attribute by itself in your filter. Example: "profiles"(If you add "profiles.identifier" to your filter without including "profiles" too, updates to this plural will not trigger a webhook.) |
Your filter:
"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
"": {
"properties": {
}
}
}
}2. Review & finalize filter
Required: Copy your filter above ( ) and paste into the text area below.
If you don’t need to make any changes, move to the next page.
If you need to refine or expand this filter, make your configuration changes directly in the text area above before moving to the next page.
- Common filter configurations:
If you configure a single webhook to be triggered by more than one event (entityCreated, entityUpdated, and/or entityDeleted), you’ll need to apply your filter criteria for each event individually.
See the example below, which applies filter properties to the entityCreated event and the entityDeleted event for a single webhook subscription.
"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
"entityCreated": {
"properties": {
"captureApplicationId": {
"const": "aabc1de2f3ghi4jklm5n67opq8"
},
"entityType": {
"const": "user"
}
}
},
"entityDeleted": {
"properties": {
"captureApplicationId": {
"const": "aabc1de2f3ghi4jklm5n67opq8"
},
"entityType": {
"const": "user"
}
}
}
}
}
If you’d like to receive webhook notifications across all your Identity Cloud applications, simply don’t include the "captureApplicationId" property in your filter (remove it from the "properties" array above).
If you’d like to receive webhook notifications across multiple Identity Cloud applications, but not all of them, use the enum keyword and array format below to list multiple application IDs in your filter. This should replace the const keyword and value pair generated by the Build-A-Filter, which is used to filter on just one application.
"captureApplicationId": {
"enum": ["aabc1de2f3ghi4jklm5n67opq8", "nmub5w3rru9k6rzupqaeb7bbwv6jn658"]
}
If you’d like to receive webhook notifications across all entity types, simply don’t include the "entityType" property in your filter (remove it from the "properties" array above).
If you’d like to receive webhook notifications across multiple entity types, but not all of them, use the enum keyword and array format below to list multiple entity types in your filter. This should replace the const keyword and value pair generated by the Build-A-Filter, which is used to filter on just one entity type.
"entityType": {
"enum": ["user", "user_patients"]
}
If you’d like to receive webhook notifications across all clients/properties, simply don’t include the "captureClientId" property in your filter (remove it from the "properties" array above).
If you’d like to receive webhook notifications across multiple clients, but not all of them, use the enum keyword and array format below to list multiple client IDs in your filter. This should replace the const keyword and value pair generated by the Build-A-Filter, which is used to filter on just one client.
"captureClientId": {
"enum": ["hpb89khtzhr8c7htnfdensfjcs5kmnhc", "j6uqcjqmsmzkz6pqrz3ndumgdhhaavgp"]
}
If you are configuring a webhook for the entityUpdated event, you can filter based on which schema attributes are updated.
If you would like to receive a webhook notification when any attribute in the user record is updated, simply leave the "attributes" property out of the filter (remove it from the "properties" array above). By default, entityUpdated webhooks will send a notification when any change is made to the user record.
Note that this is typically not desired, since it includes attributes such as lastLogin which updates automatically every time the user logs in. If you only want to be notified when user-facing profile data is changed, you must list out all applicable attributes in the "attributes" property of your filter.
Let’s say you create a webhooks subscription today for the entityCreated event only, and you add a corresponding filter to only receive notifications from your Production application for that event. In the future, you may decide to add the entityDeleted event to the same subscription. If you add this event to your configuration without adding a corresponding filter at the same time, your Production receiver endpoint will start receiving notifications for record deletions from ALL your Identity Cloud applications (e.g. Development, Staging, and Production).
To more strictly control the sending of webhook notifications, you can add the following key-value pair at the root-level within your filter:
"additionalProperties": false
Adding this parameter and value will discard notifications from any event in your webhooks subscription that does not have a corresponding filter. (When this parameter is not included, it is set to true by default.)
Filter example:
"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
"entityCreated": {
"properties": {
"captureApplicationId": {
"const": "aabc1de2f3ghi4jklm5n67opq8"
}
}
}
},
"additionalProperties": false
}
Learn More: The filter is given in JSON Schema, a mini-language used to build advanced filtering. As such, it is possible to do much more with the filter and to create something quite complicated. In the vast majority of cases, your webhooks filter will not need to do more than what is presented on this page. However, if you’re interested in learning more, see json-schema.org.