Webhook

Filters and Reducer

Filters and Reducer are configurations used to refine the webhook payload of the subscribed events. They are configured during the webhook event subscription to ensure the subscribers receive only relevant information. They also reduce unnecessary data processing. Filters apply conditions to the incoming payload, and Reducer picks up the specific fields in the payload and restructures them.

The Filters and Reducer is available for the following broadcaster types:

• Kafka
• Amazon EventBridge
• Google Pub/Sub
• Temporal
• REST

Prerequisite

We use JSONPath expression in Filters and Reducer to traverse to an element in the JSON structure. JSONPath is a query language for JSON that is used to select and extract data from a JSON payload.

Filters allows selective delivery of payload to subscribers by evaluating the given conditions and checks on the payload data. They are configured by adding a filters field under the event-key object in the events_map array during webhooks setup. Refer to Webhook Configuration to learn more.

Structure

FILTERS = EXPRESSION | LOGICAL_CONNECTOR

LOGICAL_CONNECTOR = {
  logic:      "and" | "or"
  conditions: [FILTERS, ... FILTERS]
}

EXPRESSION = {
  query:      "string"
  condition:  "string"
}

• Filters: Filters can either be an Expression (simple) or a Logical Connector (nested).
  
• Logical Connector: A Logical Connector consists of multiple (maximum 5) Filters connected by a logical operator ("and" or "or").
• Expression: An Expression consists of a query and a condition.
  
  • query: A JSONPath expression used to select specific fields.
    
  • condition: A function that takes the selected field value and returs a boolean value.
    The payload passes through only when the return of this function is true.

Example

Simple Filter

filters: {
  query: "$.articles[*].size",
  condition: "size => size === 'S'",
}

Nested Filter

filters: {
  logic: "or",
  conditions: [
    {
      logic: "and",
      conditions: [
        {
          query: "$.articles[0].track_inventory",
          condition: "(track_inventory) => { return track_inventory }",
        },
        {
          query: "$.articles[0].size",
          condition: "(size) => size === 'S'",
        }
      ]
    },
    {
      query: "$.articles[0].is_set",
      condition: "(is_set) => is_set === true",
    },
  ],
}

Best Practices

• Keep Conditions Focused: Write short, single-purpose evaluations for clarity and simplicity.
• Return Boolean Values: Ensure conditions return true or false for easy understanding and predictable behavior.
• Avoid Inefficient Practices: Do not use loops, undefined variables, or imports within conditions.
• Ensure Idempotency: Functions must always return the same result for the same input to maintain reliability.
• Optimize for Performance:
  • Simple and concise logic is crucial to prevent delays in webhook delivery.
  • Remember, each condition adds to the overall evaluation time.

Reducer restructures and minimizes the payload by picking only the specified fields before being sent to the subscriber. Payload reduction can be substantial for certain events, ranging from 1 MB to 4 MB. However, not all the information within these payload are needed by the extensions.

Reducer is configured by adding a reducer field under the event-key object in the events_map array during webhooks setup. Refer to Webhook Configuration to learn more.

You can create any object structure that would fit your need, but ensure that all values must be a valid JSONPath. If the result of the given JSONPath is an array (or an array of arrays), then the same value would be sent in the given key. You can access any field in the payload using JSONPath syntax.

Example

reducer: {
  article: [
    {
      my_id: "$.articles[0].id",
      uid: "$.articles[0].uid",
      fynd_item_code: "$.articles[0].fynd_item_code",
      tax_identifier: {
        hsn: "$.articles[*].tax_identifier.hsn_code_id"
      }
    }
  ]
}

Full Example

Let's take an example of a webhook event triggered when a new article (product) is created in an inventory management system. The payload contains detailed information about the article, including inventory data, pricing, dimensions, manufacturer, trader, tax details, and other metadata.

JSON Payload

{
  "event": {
    "id": "SwMRxpbfuJmVWjwVZiRFVHxDDB26IB2Yw9x3sL/NU+0=",
    "name": "article",
    "version": "2",
    ...
  },
  "payload": {
    "articles": [
      {
        "id": "n32ANJ28BNvu12891sasSd",
        "uid": "1543_1730818125374",
        "fynd_item_code": "BRUNT1730818125374",
        "country_of_origin": "India",
        "seller_identifier": "1730818125374",
        "size": "OS",
        "item_id": 7507094,
        "total_quantity": 100,
        "track_inventory": true,
        "is_set": false,
        "is_active": true,
        "stage": "verified",
        "company": { "id": 1049 },
        "price": {
          "transfer": 0,
          "effective": 1100,
          "currency": "INR",
          "marked": 1100,
          "updated_at": "2024-11-05T14:48:59.177454"
        },
        "tax_identifier": {
          "hsn_code_id": "672a1fe9a4c952cbe8850fae"
        },

        ...

      }
    ]
  },
  "sales_channel_id": "672a10d3290aa3fb94f2674e",
  ...
}

Apply Filters

Let's use Filters to only deliver the articles with:

• Company id: 1049
  AND
• Either:
  • The total quantity is greater than or equal to 10
    OR
  • The effective price is less than 1000

company.id == 1049 && (total_quantity >= 10 || price.effective < 1000)

filters: {
  logic: "and",
  conditions:[
    {
      query: "$.articles[*].company.id",
      condition:"c_id => c_id === 1049"
    },
    {
      logic: "or",
      conditions:[
        {
          query: "$.articles[*].total_quantity",
          condition:"quantity => quantity >= 10"
        },{
          query: "$.articles[*].price.effective",
          condition:"price => price < 1000"
        }
      ]
    }
  ]
}

The sample data will pass through because company.id is 1049 and total_quantity is 100 (>= 10).

Apply Reducer

Next, we apply a Reducer to pick the first article and extract only the required fields (id, uid, fynd_item_code, price.effective, and tax_identifier.hsn_code_id) from the article and create a compact, customized payload for the subscriber. The reducer specifies which fields to extract and how to restructure the data.

reducer: {
  article: [
    {
      my_id: "$.articles[0].id",
      uid: "$.articles[0].uid",
      fynd_item_code: "$.articles[0].fynd_item_code",
      tax_info: {
        hsn: "$.articles[0].tax_identifier.hsn_code_id",
        price: "$.articles[0].price.effective",
      }
    }
  ]
}

Final Result

After applying the Filters and Reducer, the payload that reaches the subscriber will be the following:

{
  "articles": [
    {
      "my_id": "n32ANJ28BNvu12891sasSd",
      "uid": "1543_1730818125374",
      "fynd_item_code": "BRUNT1730818125374",
      "tax_info": {
        "hsn": "672a1fe9a4c952cbe8850fae",
        "price": 1100
      }
    }
  ]
}

We have effectively filtered the payload to only recieve data based on a given condition and restructured the payload to our specific needs.