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:

ClaimDescription
captureApplicationIdUnique identifier of the ​Akamai​ Identity Cloud application associated with the event.
captureClientIdUnique identifier of the API client associated with the event.
entityTypeName of the entity type database associated with the event. This claim won't appear if no user accounts (and, as a result, no entity types) are associated with the event.
globalSubURI that points to the user record within the Identity Cloud user profile store. For example:

"sub": "capture-v1://us.janraincapture.com/zzyn9gy9r8xdy5zkru4y54syk6/user/ 6b004bc5-179c-45c2-815d-31b06169371d"

In the preceding URI, zzyn9gy9r8xdy5zkru4y54syk6 represents the unique identifier of the Identity Cloud application and 6b004bc5-179c-45c2-815d-31b06169371d represents the user’s UUID (Universally Unique Identifier).This claim is primarily for internal Identity Cloud use.
subUUID of the user account associated with the event (for example, the UUID of the user profile that was just modified). This claim won't appear if no user accounts are associated with the event.
attributesUser profile attributes (if any) associated with the event. Note that the entityUpdated event is the only event type that includes user profile attributes: the attributes claim doesn't appear in entityCreated or entityDeleted events.
idUnique ​Akamai​ customer ID.

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.


Did this page help you?