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.