What a Webhook event filter can filter on

The payload for a Webhooks v3 event notification is composed of a series of “claims” that specify an event’s properties and property values. Each claim is a key/value pair, with each pair containing – well, a key (the property name) and a value (the property value). For example, a barebones event payload (the kind issued when testing event delivery) looks similar to this:

{
  "aud": [
    "https://webhook.site/eeb46d8c-9fc0-42e4-b2d1-c0dc917031b1"
  ],
  "events": {
    "test": {
      "id": "e6e15d40-54e8-440f-bb66-2c490e60a7eb"
    }
 },
  "iat": 1628785553,
  "iss": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/webhooks",
  "jti": "be0cad30-3f72-40c5-8f92-450ad0e06c36",
  "toe": 1628785553
}

As you can see, the payload includes half a dozen or so key/value pairs (for example, "jti": "be0cad30-3f72-40c5-8f92-450ad0e06c36"). When it comes to writing Webhook filters, however, the only one of these key/value pairs that matters is the events claim (marked in red). Your webhook filters can only reference the items found in the value portion of the events claim. In the preceding example, that means we can only filter on the test claim; that’s because it’s the only key/value pair included in the events claim.

"events": {
    "entityUpdated": {
       "captureApplicationId": "zzyn9gy9r8xdy5zkru4y54syk6",
       "captureClientId": "elrrniux51a3nrhfwzklvz3t46lb5n2m",
       "entityType": "user",
       "globalSub": "capture-v1://us.janraincapture.com/zzyn9gy9r8xdy5zkru4y54syk6/user/6b004bc5-179c-45c2-815d-31b06169371d",
       "sub": "6b004bc5-179c-45c2-815d-31b06169371d",
       "attributes": [
           "email"
           ],
       "id": "e0a70b4f-1eef-4856-bcdb-f050fee66aae"
     }
    ]

A more realistic example of the events claim will look like this:

In this case, we have a large number of claims that can be referenced in a Webhooks filter; these claims are summarized in the following table:

In a Webhooks filter (at least for the entityUpdated event type), you can reference any of the claims included in the table.

📘

The parenthetical comment at least for the entityUpdated event type is important: different event types will have different claims.

To be honest, you’ll rarely want to (or need to) filter on some of these properties: for example, there’s typically little reason to filter by sub or by id. Instead, you’re more like to filter your webhooks subscriptions by :

• Application ID (captureApplicationId). This enables you to do things like ensure that you only receive events from your production application and don’t receive events from your development application.

• By login client (captureClientId).

• By user profile attributes (attributes). For most organizations, there are only a few user profiles attributes that are truly of interest: password, email address, mobile device number, perhaps some custom attributes of your own. With a filter can automatically discard any events that don’t involve changes to at least one of those attributes.

• By entity type (entityType).

We should also note that one thing you can’t filter on is any sort of personally identifiable information: a user’s actual email address, a user’s phone number, a user’s city of residence, etc. You can’t filter on these values because event notifications only include which attributes have been changed in a user profile; they don’t include either the old or the new values of those attributes. At best, you’ll know that the user with the UUID 6b004bc5-179c-45c2-815d-31b06169371d changed their email address. What was their old email address, and what’s their new email address? That information isn’t exposed in an event notification.