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.
Updated over 1 year ago