Validate a webhook event filter

Before you begin writing webhook filters itโ€™s important to understand how (or even if) filter validation takes place. To begin with, the Identity Cloud always verifies that the JSON syntax used in your API callโ€™s request body is valid. For example, suppose you try using this request body:

"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"properties": {
  "entityUpdated": {
    "properties": {
      "captureApplicationId": {
        "const": "zzyn9gy9r8xdy5zkru4y54syk6"
         }
        }
      }
    }
  }

The preceding is not valid JSON: itโ€™s missing a curly brace ( { ) at the beginning. And because this isnโ€™t valid JSON, the command fails with the following error:

{
  "type": "/invalid-request-body",
  "status": 400,
  "title": "Invalid request body",
  "details": "Request body is not valid JSON"
}

Thatโ€™s to be expected. In addition to generic JSON validation like this, the Identity Cloud also performs basic validation on the filter schema. For example, in this sample filter we used the claim name x:

{  
  "filter": {
    "$schema": "http://json-schema.org/draft-07/schema",
      "x": {
        "entityUpdated": {
          "properties": {
            "captureApplicationId": {
              "const": "zzyn9gy9r8xdy5zkru4y54syk6"
            }
          }
        }
      }
    }
  }

Thatโ€™s a mistake: filters donโ€™t have a claim named x. As a result, the API call fails with the following error:

{
  "type": "/validation-error",
  "status": 400,
  "title": "Bad Request",
  "invalid-body-params": [
    {
      "name": "filter",
      "reason": "filter is invalid JSON Schema"
    }
  ]
}

Note that this error message doesnโ€™t tell us exactly what went wrong: the x claim isnโ€™t even mentioned. However, the reason value (filter is invalid JSON schema) tells us that thereโ€™s a problem with the way the filter has been constructed. The overall JSON is fine: itโ€™s the filter that's causing the problem.

In other words, the Identity Cloud validates the basic JSON used in the API call, and it validates the basic JSON schema used to construct the filter. However, what it wonโ€™t do is validate any values you use in your filters. For example, here weโ€™re telling the webhook subscription that we want to filter on application ID x:

{  
  "filter": {
    "$schema": "http://json-schema.org/draft-07/schema",
    "properties": {
      "entityUpdated": {
        "properties": {
          "captureApplicationId": {
            "const": "x"
            }
          }
        }
      }
    }
  }

This API call will succeed, and weโ€™ll end up with a webhook subscription that triggers only for events where the application ID is x. And thatโ€™s a problem: no one has (or probably ever will have) an application with the ID x. However, the Webhooks v3 API doesnโ€™t know that: it doesnโ€™t try to verify that application IDs or entity type names or user profile attributes actually exist. Instead, the API accepts the values you enter and adds those values (and the accompanying filter) to the webhook subscription. If a webhook filter isnโ€™t working the way you thought it would, a good place to start troubleshooting is with the property values used in that filter. Make sure that the values you entered are valid, and that you use the proper letter casing when you enter them: the Identity Cloud user profile attribute is displayName, not displayname or DisplayName.


๐Ÿ‘

Another thing to check for: see if you have multiple subscriptions monitoring the same event type. If you do, subscription A might be overriding subscription B (and/or vice-versa). See Webhook filter examples for more information.