Guide

Webhooks v3 supported event filter keywords

Suggest Edits

When it comes to creating filters for your Webhook subscriptions, the Identity Cloud uses a subset of the JSON Schema draft 7 validation language. The keywords that can be included in an Identity Cloud filter are summarized in the following tables.


General validation

KeywordDescription
constTo validate, a value must exactly match the const value. For example, suppose you use the captureApplicationId property and set the const keyword to xj2dmg2mqsm6a8gx89cwn3fu929p4pd. In that case, only events where the captureApplicationId is equal to xj2dmg2mqsm6a8gx89cwn3fu929p4pd pass validation.

Note that, when using const, matches must be exact: validation fails if you try to use a wildcard value such as xj2dmg2*.
enumValidation requires a value to be equal to at least one of the items in the enum array. For example, suppose you have the following schema:

{ "enum": ["red", "orange", "yellow", "green", "blue", "indigo", "violet"] }

In that case:

* The value orange passes validation, because orange is in the enum array.
* The value pink fails validation because pink isn’t in the enum array.
additionalPropertiesWhen set to false, indicates that all unfiltered events are automatically ignored. See Create a webhook event filter for more information.

Numeric and string validation

KeywordDescription
exclusiveMaximumSpecifies the maximum value for a number, not including the specified maximum itself (i.e., validation requires a value to be less than the specified maximum). For example, suppose you set exclusiveMaximum to 7. In that case:

* The value 6 passes validation because it’s less than 7.
* The value 8 fails validation because it’s not less than 7.
* The value 7 fails validation because it’s not less than 7.
exclusiveMinimumSpecifies the minimum value for a number, not including the specified minimum itself (i.e., validation requires a value to be greater than the specified minimum). For example, suppose you set exclusiveMinimum to 10. In that case:

* The value 12 passes validation because it’s greater than 10.
* The value 4 fails validation because it’s not greater than 10.
* The value 10 fails validation because it’s not greater than 10.
formatEnables more-specific validation of string values. The following format types are supported:

* date-time. Date and time in the format Year-Month-Day:Hour-Minute-Second-UTC offset. For example: 2020-10-11T17:06:0+00:00.

* time. Time of day in the 24-hour format Hour-Minute-Second-UTC offset. For example: 17:06:0+00:00.date. Date in Year-Month-Day format. For example: 2021-12-19.

* duration. Duration per ISO 8601 ABNF for duration. For example: P5Y6M9DT11H30M7S (five years, six months, nine days, eleven hours, thirty minutes, and seven seconds.)

* email. Internet email address per RFC 5322, section 3.4.1.

* idn-email. Internationalized form of an Internet email address per RFC 6531. Supports non-ASCII-encoded languages such as Arabic, Chinese, and Cyrillic.

* hostname. Internet host name per RFC 1123, section 2.1.

* idn-hostname. Internationalized Internet host name, per RFC 5890, section 2.3.2.3. Supports non-ASCII-encoded languages such as Arabic, Chinese, and Cyrillic.

* ipv4. IPv4 address using dotted-quad ABNF syntax (defined in RFC 2673, section 3.2). For example: 192.168.1.13

* ipv6. IPv6 address per RFC 2373, section 2.2. For example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334.

* uuid. Universally Unique Identifier per RFC 4122. For example: b8097975-93c7-46db-8cfe-19609e67eadb.

* uri. Universal resource identifier (URI) per RFC 3986.

* uri-reference. URI Reference (either a URI or a relative-reference) per RFC 3986, section 4.1.

* iri. Internationalized equivalent of a URI per RFC 3987. Allows the use of characters and formats derived from non-English languages.

* iri-reference. Internationalized equivalent of a uri-reference per RFC 3987. Allows the use of characters and formats derived from non-English languages.

* uri-template. URI Template per RFC 6570. For example: http://documentation.akamai.com/~{username}/.

* json-pointer. JSON Pointer per RFC 6901.

* relative-json-pointer. Relative JSON pointer.

* regex. Regular expression per the ECMA 262 dialect.
maximumValidation requires a number to be less than or equal to the maximum. For example, suppose you set the maximum for a numeric value to 603. In that case:

* The value 13 passes validation because less than the maximum value.
* The values 603 passes validation because it’s less than or equal to the maximum.
* The value 903 fails validation because it is not less than or equal to the minimum.
maxLengthMaximum number of characters that a string can possess in order to pass validation: the value must have a “length” less than or equal to the maxLength. For example, suppose you set maxLength to 10. In that case:

* The ID abcdefgh passes validation because it has 8 characters: 2 less than the maximum number of allowed characters.
* The ID abcdefghijklm fails validation because it has 13 characters: 3 more than the maximum number of allowed characters.
* The ID abcdefghij passes validation because it has 10 characters: it doesn’t exceed the maximum number of allowed characters.
minimumValidation requires a number to be greater than or equal to the minimum. For example, suppose you set the minimum for a numeric value to 603. In that case:

* The value 903 passes validation because it exceeds the minimum value.
* The values 603 passes validation because it’s greater than or equal to the minimum.
* The value 13 fails validation because it is not greater than or equal to the minimum.
minLengthMinimum number of characters that must be in a string for that value to pass validation: the value must have a “length” greater than or equal to the minLength. For example, if minLength is set to 7 then:

* The string value “seventeen” passes validation because it has at least 7 characters.
* The string value “seventy” passes validation because it has exactly 7 characters.
* The string value “seven” fails validation because it doesn’t have at least 7 characters. The numeric value 7 fails validation because it’s not a string.
multipleOfTo pass validation, a number must be evenly divisible by the multipleOf value (i.e., there is no remainder). For example, suppose you set multipleOf to 4. In that case:

* The value 12 passes validation, because 12 is evenly divisible by 4 (12 divided by 4 = 0).
* The value 10 fails validation, because 10 is not evenly divisible by 4 (10 divided by 4 = 2.5).
patternValidates a string against a regular expression. Regular expressions are composed using the ECMA 262 regular expression dialect. For example, suppose you use the following regular expression, in which validation occurs only if the value begins with the lowercase letters a, b, or c:

^[abc]

In that case:

* The string value “barracuda” passes validation because it begins with a lowercase b.
* The string value “Barracuda” fails validation because it begins with an uppercase b.
* The string value “shark” fails validation because it does not begin with a lowercase a, b, or c.

Annotations and comments

KeywordDescription
$commentDescriptive information typically aimed developers. You can intersperse multiple comments throughout a filter.
defaultSpecifies the value that should be used if no other value was supplied; for example, US might be the default value for a country attribute. Note, however, that default is used only to help explain the schema and how it works: if no value is supplied the default value is not substituted nor is the default value used in validation. For example, the following schema sets US as the default for the country attribute:

"country": { "default": "US" ] }

However, if a user fails to enter a value for the country attribute then the country attribute will remain as-is: the null value will not be replaced by the default value.
descriptionString value that explains the schema and what it’s used for. The description is ignored when the schema is validated. For example:

{ "description": "This schema validates the Capture client ID." }
examplesSample values that, if used, would validate. These values are provided to help explain how the schema works, and aren’t actually used in validation. For example:

"examples": [ "karim.nafir@mail.com", "augustjosephspringer@gmail.com" ]
titleBrief title applied to the schema. For example:

{ "title": "entityCreated Validation" }

Arrays and array validation

KeywordDescription
containsValidation requires a value to match at least one of the items in the contains array. For example, suppose we have the following schema, which specifies that the array being validated must contain a numeric value:

{ "type": "array", "contains": { "type": "number" } }

In that case:

* The array [1, 2, 3, 4, 5] passes validation because it contains at least one numeric value.
* The array ["A", "B", "C", "D", 5] passes validation because it contains at least one numeric value.
* The array ["A", "B", "C", "D", "E"] fails validation because it doesn’t contain a numeric value.
itemsValidation requires each item in an array to meet the specified schema. For example, suppose we have the following schema, which specifies that all the items in an array be numbers:

{ "type": "array", "items": { "type": "number" } }

In that case:

* The array [1, 2,3 4, 5] passes validation because it contains nothing but numbers.
* The array [1, 2,3 ,4, "five"] fails validation because it includes a string value.
maxContainsValidation requires that the value match no more items in an array that the number specified by maxContains. For example, suppose maxContains is set to 2 using the following array:

["A", "B", "C", "D", "E", "F", "G"]

In that case:

* The array ["A", "B"] passes validation because it matches no more than two items in the target array.
* The array ["A", "B", "X", "Y", "Z"] passes validation because it matches no more than two items in the target array.
* The array ["A", "B", "E", "F", "G"] fails validation because it matches more than two items in the target array.
* The array ["A", "X", "Y", "Z"] passes validation because it matches only one item (i.e., less than 2 items) in the target array.
maxItemsAn array must contain no more than the number of items specified by the maxItems value. For example, suppose you set the maxItems for an array to 3. In that case:

* The array ["A", "B"] passes validation because it has fewer than the maxItems.
* The array ["A", "B", "C"] passes validation because it 3 items: less than or equal to the number specified by maxItems.
* The array ["A", "B", "C", "D"] fails validation because it has more items (4) that the number specified by maxItems.
minContainsValidation requires that the value match, at the very least, the number of items in an array specified by minContains. For example, suppose minContains is set to 2 using the following array:

["A", "B", "C", "D", "E", "F", "G"]

In that case:

* The array ["A", "B"] passes validation because it matches at least two items in the target array.
* The array ["A", "B", "X", "Y", "Z"] passes validation because it matches at least two items in the target array.
* The array ["A", "B", "E", "F", "G"] passes validation because it matches at least two items in the target array.
* The array ["A", "X", "Y", "Z"] fails validation because it matches only one item in the target array. Note that this value can be set to 0. However, unless the maxContains validation is included, anything set to minContains = 0 will always pass validation.
minItemsAn array must contain at least the minimum number of items specified by the minItems value. For example, suppose minItems is set to 3. In that case:

* The array ["A", "B", "C", "D"] passes validation because it has more than 3 items.
* The array ["A", "B", "C"] passes validation because it has exactly 3 items.
* The array ["A", "B"] fails validation because it doesn’t have at least 3 items.
uniqueItemsSpecifies that all the items in an array must be unique. For example, suppose you set uniqueItems to true. In that case:

* The array [“A”, “B”, “C”, “D”] passes validation because all 4 items (A, B, C , D) are unique.
* The array [“A”, “B”, “C”, “A”] fails validation because there are duplicate items (two instances of the letter A).

If uniqueItems is set to false (or is omitted), then it doesn’t matter whether or not the items in an array are unique.

Schemas and schema validation

KeywordDescription
$schemaDefines the JSON “dialect” used in creating (and required for interpreting) the schema. Currently Webhooks only accepts the http://json-schema.org/draft-07/schema schema:

"$schema": "http://json-schema.org/draft-07/schema",
allOfA value must validate against all the items in a sub-schema. For example, the following schema specifies a number that has a minimum value of 5 and a maximum value of 10:

{ "allOf": [ { "type": "number", "minimum": 5 }, { "type": "number", "maximum": 10 } ] }

In this case:

* The value 7 passes validation because it’s a number and it's between 5 and 10.
* The value 14 fails validation because, even though it is a number, it does not fall between 5 and 10.
* The string value “seven” fails validation because it isn’t a number.
anyOfA value must validate against at least one of the items in a sub-schema. For example, the following schema specifies a value that is either a string or a number:

{ "anyOf": [ { "type": "string" }, { "type": "number" } ]}

In this case:

* The value 1219 passes validation because it’s a number.
* The value “twelve nineteen” passes validation because it’s a string.
* The value true (a Boolean value) fails validation because it’s neither a number nor a string.
oneOfA value must validate against one, but only one, of the items in a sub-schema. For example, suppose you have the following schema:

{ "oneOf": [ { "type": "number", "multipleOf": 6 }, { "type": "number", "multipleOf": 4 } ] }

In that case:

* The value 18 passes validation because it’s a multiple of 6 (6 x 3 = 18) but isn’t a multiple of 4.
* The value 16 passes validation because it’s a multiple of 4 (4 x 4 = 16) but isn’t a multiple of 6.
* The value 12 fails validation because it’s a multiple of both 6( 6 x 2 = 12) and 4 (4 x 3 = 12).

Data type validation

KeywordDescription
typeSpecifies the datatype of a value. Allowed datatypes are:

* string. Includes letters, numbers, and special characters.
* number. Includes all numbers, including negative numbers and numbers with decimal points.
* integer. Includes whole numbers only, either positive or negative.
* object. Uses key/value pairs.
* array. Can include items of different datatypes.
* boolean. True/false values.
* null. Indicates that no values has been assigned to an element.

Objects and object validation

KeywordDescription
dependentRequiredIf the object includes a specified property then it must also include one or more related properties in order to validate. For example, if an object includes a creditCard property you might also require a phoneNumber and homeAddress property. In that case, phoneNumber and homeAddress are dependent properties. For example:

{ "type": "object", "properties": { "name": { "type": "string" }, "creditCard": { "type": "number" }, "phoneNumber": { "type": "string" } "homeAddress": { "type": "string" } }, "required": ["name"], "dependentRequired": { "creditCard": ["phoneNumber", "homeAddress"] } }

In the dependentRequired portion of the schema, creditCard is the target property, and phoneNumber and homeAddress are the other two properties that must be present along with creditCard. If any of these properties are missing, the objects fails validation.
maxPropertiesWhen working with an object, that object can contain no more properties than the number specified by the maxProperties value. For example, suppose you set the maxProperties for an object to 2. In that case:

* The object {"name": "Bob", "id": "071267"} passes validation because it has only two properties (name and id).
* The object {"name": "Bob", "id": "071267", "creationDate": "10/18/2020"} fails validation because it has only three properties: name, id, and creationDate.
minPropertiesWhen working with an object, that object must contain at least the number of properties specified by the minProperties value. For example, suppose you set the maxProperties for an object to 3. In that case:

* The object {"name": "Bob", "id": "071267", "creationDate": "10/18/2020"} passes validation because it has at least 3 properties: name, id, and creationDate. The object {"name": "Bob", "id": "071267"}fails validation because it has only two properties (name and id).
patternPropertiesEnables you to use regular expressions to define an object schema. For example, consider the following (and extremely simple schema):

{ type: "object", patternProperties: { "Name$": {type: "string"} } }

When using patternProperties, the regular expression Name$ checks for property names that end in name (for example, firstName).

Meanwhile, the value (type: “string”) is the validation requirement. With his simple schema, an object can’t pass validation unless all properties with a name ending in name are string properties. For example:

* The object {"firstName": "Bob"} passes validation.
* The object {"first": 22} passes validation. Because there aren’t any property names that end in name it doesn’t matter that the lone property value is a number rather than a string.
* The object {"firstName": "Robert". "lastName": "Jones", "nickname": "Bob", "userNickname": true} fails validation. That’s because the userNickname property is a Boolean rather than a string.
propertiesDefines the properties of an object. If any of the defined properties are used in the object being validated, they must meet the property definitions (for example, a given property must be a string value rather than a Boolean value). However, the object doesn’t have to include all the defined properties, and can even include properties that haven’t been defined.

For example, suppose have the following schema, which defines an object with 2 properties (id and name):

{ "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" } } }

In this case:

* The object {"id": 122463, "name": "Bob"} passes validation.
* The object {"id": 122463} passes validation even though it doesn’t include the name property.
* The object {"id": 122463, "name": "Bob", "membershipType": "employee"} passes validation even though it includes an undefined property (membershipType).
* The object {"id": "122463", "name": "Bob"} fails validation because the id (“122463”) is a string rather than a number.
propertyNamesEnables you to validate property names in an object against a specified schema (and by using regular expressions). For example, suppose you require all property names to begin with the string value akamai. In that case, you can use a validation schema similar to this:

{ "type": "object", "propertyNames": { "pattern": "^akamai" } }

With the preceding, a property name like akamaiId passes validation; a property name like customerId would not pass validation.
requiredValidation requires an object to include all the properties specified in the required array. For example, this schema requires the object includes the captureClientId and entityType properties:

"required": [ "captureClientId", "entityType" ]

Conditional actions

KeywordDescription
if - then - elseEnables you to apply different validation criteria depending on the values assigned to specified properties. For example, consider this schema:

"if": { "properties": { "captureApplicationId": { "const": "htb8fuhxnf8e38jrzub3c7pfrr" } } }, "then": { "properties": { "captureClientId": { "const": " xj2dmg2mqsm6a8gx89cwn3fu929p4pd"} }, "else": { "properties": { "captureClientId": { "const": " 3bchk5hsx6v58dkn288nbybmxfyk32u7"} }

In the preceding schema, we use this syntax to cee if the Capture application ID reported in a Webhook notification is equal to htb8fuhxnf8e38jrzub3c7pfrr:

"if": { "properties": { "captureApplicationId": { "const": "htb8fuhxnf8e38jrzub3c7pfrr" } } },

If this is true, if the notification involves the specified Capture application, we then use this section to verify that the client ID isxj2dmg2mqsm6a8gx89cwn3fu929p4pd

:"then": { "properties": { "captureClientId": { "const": " xj2dmg2mqsm6a8gx89cwn3fu929p4pd"} },

If the client ID isxj2dmg2mqsm6a8gx89cwn3fu929p4pd then the notification passes validation.

And what if the Capture application ID isn’t htb8fuhxnf8e38jrzub3c7pfrr? In that case, we check to see if the client ID is 3bchk5hsx6v58dkn288nbybmxfyk32u7:

"else": { "properties": { "captureClientId": { "const": " 3bchk5hsx6v58dkn288nbybmxfyk32u7"} }

If true, then the notification passes validation. Admittedly, that all sounds a bit confusing, to say the least. In a nutshell, however, here’s what our if – then – else statement is doing:

1. Checks to see if the captureApplicationId property is equal to htb8fuhxnf8e38jrzub3c7pfrr.
2a. If true, the statement proceeds to the then clause.
2b. If false, the statement proceeds to the else clause.

Bonus: Using annotations and comments in a filter

For simple filters (e.g., a filter that only forwards entityUpdated events associated with a specified application) you might not need any descriptive elements: the filter will likely be self-explanatory as it is. As you start to create more-complex filters, however, that might not always be true: in cases like that, it might be useful to include a filter description or an occasional comment. In the following filter we added the title, description, and $comment keywords, just to give you an example of how you can annotate filters:

"filter": {
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "Application ID Filter",
  "description": "This filter limits forwarded data to those events that include one of the two captureApplicationIds referenced by the enum keyword."
    "properties": {
      "entityUpdated": {
        "properties": {
          "captureApplicationId": {
            "enum": ["zzyn9gy9r8xdy5zkru4y54syk6", "htb8fuhxnf8e38jrzub3c7pfrr"],
           "$comment": "You can find application IDs by going to the Manage Application page in Console."
          }
        }
      }
    }
  }

Updated almost 2 years ago