⚙️Advanced Filter Patterns

Learn various filter combinations to build both simple and complex filter for only listening to certain Farcaster events.

Subscription filtering is used to decide what events an endpoint will receive based on the webhook event payload. The subscription filter is an enriched JSON syntax for both simple and complex filters (such as special logical and arithmetic operators $or, $gte, $eq).

​Simple filters

Simple filters directly match keys to values, and they can be nested. They can also match items in an array.

​Direct object match

This filter is used to validate simple JSON webhook payloads.

Filter Schema

{
  "userId": "602"
}

Matched Event Payload

{
  "userId": "602", // Match userId with value "602"
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  // ...Other fields
}

​Nested object match

This filter is used to validate nested webhook payloads.

Airstack webhooks filter only accept nested filters up to 3 levels. More than 3-level nesting will result in error.

Filter Schema

{
  "socialCapital": {
    "socialCapitalRank": 1
  }
}

Matched Event Payload

{
  "socialCapital": {
    "socialCapitalScore": 279,
    // match socialCapital.socialCapitalRank with exact value 1
    "socialCapitalRank": 1
  },
  "profileDisplayName": "dwr",
  "profileImage": "https://i.imgur.com/Y1au7ZB.jpg",
  // ...Other fields
}

​Array contains match

This filter is used to validate if there is any match in an array field in the webhook payloads.

Filter Schema

{
  "userAssociatedAddresses": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a"
}

Matched Event Payload

{
  "userId": "3761",
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    // Match with any result that contain the mentioned address
    // in the array
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  // ...Other fields
}

​Complex filters

Complex filters contain more logic such as logical operators and special operators. Complex filters are employed to filter events using one or more conditions, e.g., $or logical operator filter.

​$neq

This filter matches event which directly does not match the event type in the webhook payload.

Filter Schema

{
  "userId": {
    "$neq": "1"
  }
}

Matched Event Payload

{
  // Match with any payload that doesn't have userId value 1
  "userId": "602", 
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  // ...Other fields
}

​$or

This filter is used to match multiple conditions evaluated using OR logic as defined in the schema.

Filter Schema

{
  "$or": [
    {
      "userId": "602"
    },
    {
      "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a"
    }
  ]
}

Matched Event Payload

{
  // Match either the userId value or userAddress value
  "userId": "602",
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  // ...Other fields
}

$and

This filter is used to match multiple conditions evaluated using AND logic as defined in the schema. This can also be combined with other operators such as $or.

Filter Schema

{
  "$and": [
    {
      "$.socialCapital.$.socialCapitalRank": {
        "$lte": 100
      }
    },
    {
      "$or": [
        {
          "userId": "602"
        },
        {
          "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a"
        }
      ]
    }
  ]
}

Matched Event Payload

{
  "userId": "602",
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  "socialCapital": {
    "socialCapitalRank": 70,
    "socialCapitalScore": 100
  },
  // ...Other fields
}

​Array Contains filters

This filter is used to match keys where the value can be a range of values. It can be used in place of $or if you are comparing on the same field. The opposite of this operator $nin can be used to match keys where the value is not in a range of values.

Filter Schema

{
  "userId": {
    "$in": ["602", "2602"]
  }
}

Matched Event Payload

{
  "userId": "602", // 602 is inside the $in operator
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  "socialCapital": {
    "socialCapitalRank": 70,
    "socialCapitalScore": 100
  },
  // ...Other fields
}

​Arithmetic filters

These filters match events based on arithmetic operators. For example, the filter below will match all events where the age is greater than 1. The operators supported are $gt, $gte, $lt, $lte

Filter Schema

{
  "socialCapital": {
    "socialCapitalRank": {
      "$lte": 100
    }
  }
}

Matched Event Payload

{
  "socialCapital": {
    "socialCapitalScore": 279,
    // Only match payload with socialCapital.socialCapitalRank <= 100
    "socialCapitalRank": 1
  },
  "profileDisplayName": "dwr",
  "profileImage": "https://i.imgur.com/Y1au7ZB.jpg",
  // ...Other fields
}

​Array positional filters

These filters match events with payloads that are array either in the root or nested.

Filter Schema

{
  "$.socialCapital.$.socialCapitalRank": {
    "$lte": 100
  }
}

Matched Event Payload

{
  "socialCapital": {
    "socialCapitalScore": 279,
    // Only match payload with socialCapital.socialCapitalRank <= 100
    "socialCapitalRank": 1
  },
  "profileDisplayName": "dwr",
  "profileImage": "https://i.imgur.com/Y1au7ZB.jpg",
  // ...Other fields
}

​Regex filters

These filters match events with payloads that match the supplied regex.

Filter Schema

{
  "profileName": {
    "$regex": "^betashop"
  }
}

Matched Event Payload

{
  // Match with profileName that starts with "betashop"
  "profileName": "betashop.eth",
  "userId": "602",
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ],
  // ...Other fields
}

Developer Support

If you have any questions or need help regarding defining custom filters for your use cases, please join our Airstack's Telegram group.

More Resources

• Quickstart Guide

• Managing Webhooks

• Webhooks API Reference