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 entityUpdated events)

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": "",
	"properties": {
		"entityUpdated": {
			"properties": {
				"captureApplicationId": {
					"const": "aabc1de2f3ghi4jklm5n67opq8"
				"entityType": {
					"const": "user"
				"attributes": {
					"contains": {
						"enum": [

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:

Your filter:

"filter": {
	"$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:
Add filtering for more than 1 event
Filter on more than 1 application
Filter on more than 1 entity type
Filter on more than 1 client
Filter on all data attributes in the schema
Reject any events that do not have a corresponding filter

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