Skip to main content

Filtering Events

A webhook only receives the events its filter matches. The filter is a JSONPath filter expression, set in eventFilters.jsonExpressionFilter.jsonPathExpression (the Filter field in the Console). It is tested against each event published in your org; events from other orgs never reach your webhooks, so you don't need to filter on the org.

What a Filter Can Read​

In the expression, @ is the event. These fields are available:

PathValue
@.typeThe event type, for example connectorEntitiesChangelog.
@.sourceThe event source, for example //com.mapped/orgs/ORG.../liveQueries/LVQ....
@.idThe event ID.
@.attributes.<name>.Attr.CeStringThe value of the extension <name>, as a string, for example @.attributes.severity.Attr.CeString.

The event's data cannot be filtered on. When you need to select on something inside it, filter on type (and an extension, where the event has one) and decide the rest in your endpoint.

Operators​

OperatorMeaningExample
==, !=Equal, not equal. Strings use single quotes.@.type == 'connectorEntitiesChangelog'
=~Matches a regular expression, written between slashes.@.type =~ /^webhooks\.subscriptions\./
&&, ||And, or.@.type == 'a' || @.type == 'b'
( )Grouping.(@.type == 'a' || @.type == 'b') && @.source =~ /CON123/

An expression that is not valid, or that refers to a field the event doesn't have, simply doesn't match.

Examples​

One event type:

@.type == 'connectorEntitiesChangelog'

One live query (its ID is the last part of the source):

@.source == '//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQAERav1iu5vkp6Qhkmf1234'

Every live query in your org:

@.type == 'mapped.livequery.resultChangeNotification.v1.created'

The entity changes of one connector:

@.type == 'connectorEntitiesChangelog' && @.source =~ /\/connectors\/CON8NnmVKfa2Eq6BpBJ6Wz9hT$/

Several types:

@.type == 'webhooks.subscriptions.created' || @.type == 'webhooks.subscriptions.deleted'

Escaping in the API​

The expression is a string inside your GraphQL request, so a backslash in a regular expression must be doubled there:

eventFilters: {
jsonExpressionFilter: {
jsonPathExpression: "@.type == 'connectorEntitiesChangelog' && @.source =~ /\\/connectors\\/CON8NnmVKfa2Eq6BpBJ6Wz9hT$/"
}
}

In the Console's Filter field, type the expression as shown in the examples, with single backslashes.

Other Filter Kinds​

eventFilters also accepts timeseriesFilter and cloudEventFilter. Both are still in development; use jsonExpressionFilter.