Search Configuration with Webhooks

Learn the possibilities for configuring search in Emporix.

You can integrate the Emporix Commerce Engine with any index providers by leveraging the webhook events concept. Emporix CE recognizes all changes around a product item like the product itself, its price, category or availability related to the product. If any of the connected entities is modified, our platform prepares an index-item object which contains all the necessary data.

See the event schema for an updated index item - IndexItemUpdated.

"id": "String",
"code" : "String",
"siteCode" : "String",
"name" : "Map<String,String>", // Localized map
"description" : "Map<String, String>", // Localized map
"categoryAssignments" : [
  {
    "id" : "String",
    "code" : "String",
    "name" : "String",
    "localizedName" : "Map<String,String>", // Localized map
    "localizedSlug" : "Map<String,String>", // Localized map
    "parent" : "Object"
  }
],
"tags" : String[], // Array of strings
"popularity" : "Integer",
"prices" : [
  {
    "id" : "String",
    "itemId" : {
      "id" : "String",
      "itemType" : "String" // PRODUCT
    },
    "currency" : "String",
    "originalAmount" : "Number",
    "effectiveAmount" : "Number",
    "location" : {
      "countryCode" : "String"
    },
    "salePrice" : {
      "discountAmount" : "Double",
      "discountRate" : "Double",
      "description" : "String"
    },
    "priceModelId" : "String",
    "priceModel" : {
      "id" : "String",
      "name" : "Map<String,String>", // Localized map
      "description" : "Map<String,String>", // Localized map
      "includesTax" : "Boolean",
      "measurementUnit" : {
        "quantity" : "Double",
        "unitCode" : "String"
      },
      "tierDefinition" : {
        "tierType" : "String",
        "tiers" : [
          {
            "id" : "String",
            "minQuantity" : {
              "quantity" : "Double",
              "unitCode" : "String"
            }
          }
        ]
      }
    },
    "restrictions" : {
      "validity" : {
        "from" : "String",
        "to" : "String"
      },
      "siteCodes" : "String[]" // Array of strings
    },
    "tierValues" : [
      {
        "id" : "String",
        "priceValue" : "Double"
      }
    ],
    "mixins" : "Map<String,Object>",
    "siteCode" : "String"
  }
],
"medias" : [
  {
      "url" : "String",
      "position" : "Integer",
      "contentType" : "String",
      "customAttributes" : Map<String, Object>
  }
],
"availability" : {
  "id" : "String",
  "stockLevel" : "Double",
  "productId" : "String",
  "site" : "String",
  "available" : "Boolean",
  "popularity" : "Integer",
  "distributionChannel" : "String"
},
"mixins" : "Map<String,Object>",
"published" : "Boolean",
"available" : "Boolean"

See an example of the index-item object and what is emitted every time a product is created or updated.

{
  "availability": {
    "available": false,
    "distributionChannel": "ASSORTMENT",
    "id": "main:643dacfad50d664c58694c2d",
    "popularity": -2147483648,
    "productId": "643dacfad50d664c58694c2d",
    "site": "main",
    "stockLevel": 2313
  },
  "available": false,
  "categoryAssignments": [
    {
      "id": "79eccb8b-b163-4cb9-9528-ed9468b9f740",
      "localizedName": {
        "en": "c1"
      },
      "name": "c1"
    }
  ],
  "code": "Oranges",
  "id": "643dacfad50d664c58694c2d",
  "medias": [
    {
      "contentType": "image/jpeg",
      "customAttributes": {
        "height": 800,
        "name": "oranges.jpeg",
        "sizeKB": 156.7138671875,
        "width": 1200
      },
      "mainImage": false,
      "url": "http://res.cloudinary.com/saas-ag/image/upload/v1681763617/lsindexdbstage/media/643dad208fc03d22f4e857e6"
    }
  ],
  "popularity": -2147483648,
  "prices": [
    {
      "currency": "EUR",
      "effectiveAmount": 1.55,
      "id": "643dad10c0dc2925289a6206",
      "itemId": {
        "id": "643dacfad50d664c58694c2d",
        "itemType": "PRODUCT",
        "name": {
          "en": "Oranges"
        }
      },
      "location": {
        "countryCode": "DE"
      },
      "originalAmount": 1.55,
      "priceModel": {
        "description": {
          "en": "Default price model"
        },
        "id": "63402c86af907617bb4e1234",
        "includesTax": false,
        "measurementUnit": {
          "quantity": 1,
          "unitCode": "pc"
        },
        "name": {
          "en": "Default price model"
        },
        "tierDefinition": {
          "tierType": "BASIC",
          "tiers": [
            {
              "id": "63402c86af907617bb4e9826",
              "minQuantity": {
                "quantity": 0,
                "unitCode": "pc"
              }
            }
          ]
        }
      },
      "priceModelId": "63402c86af907617bb4e1234",
      "restrictions": {
        "siteCodes": [
          "main"
        ]
      },
      "siteCode": "main",
      "tierValues": [
        {
          "id": "63402c86af907617bb4e9826",
          "priceValue": 1.55
        }
      ]
    }
  ],
  "published": true,
  "siteCode": "main",
  "tags": [
    "product",
    "published"
  ]
}

See the event schema for a deleted index item - IndexItemDeleted.

"id": "String",
"siteCode" : "String"

See an example message that is sent when a product is deleted.

{
  "id": "643dab38a9e0f24d6bda45ee",
  "siteCode": "main"
}

The index-item payloads above are produced inside Commerce Engine whenever catalog data changes, but they do not reach your search provider on their own. The Webhook Service is the delivery layer: it forwards Index item updated and Index item deleted events to the endpoint you configure (for example by using Svix), where they can be transformed and applied to your external search index.

Without enabling the webhook service and the index-item events, your search engine has no automated way to learn about new, changed, or removed products.

Enabling webhook service

To enable the webhook service, follow these steps:

1

Open Webhooks

Log in to the Management Dashboard and go to Administration -> Webhooks.

2

Choose a webhook strategy

Choose the webhooks strategy that best suits your needs. You can select between HTTP, SVIX and SVIX SHARED.

Webhook strategy selection in Management Dashboard

For more information on webhooks strategies and configuration, see Webhooks.

3

Enable index-item events

Extend the Index item webhook details and enable the Index item updated and the Index item deleted events.

Index item updated and deleted events enabled in Webhooks

4

Configure endpoints

Depending on the chosen webhook strategy, there are different ways to configure the endpoints for receiving notifications about events happening in the system. Configure your strategy to be able to process the events.

Commerce Engine allows you to configure your own search functionality. You can choose any provider that suits your needs. For demonstration purposes of how you can configure search through the webhooks functionality, we present examples of configuring Algolia and BatteryIncluded. These are the search engines that can be configured to work with Emporix CE and Svix.

Algolia Search Provider

Use the Indexing Service for production or direct webhook forwarding for testing.

BatteryIncluded Search Provider

Use the native Indexing Service for production or direct webhook forwarding for testing.

Webhook configuration example with Svix-shared strategy

For Svix-shared strategy, use the Open Svix Dashboard option to configure the relevant endpoints. It automatically opens the Svix Dashboard where you can configure the required endpoints. See the testing example below:

1

Add an endpoint

In Svix Dashboard, go to Endpoints and choose the Add Endpoint button to start the endpoint configuration.

For testing purposes, you can use Svix Play configuration, it automatically creates a sandbox destination.

Svix endpoint URL configuration

2

Filter index-item events

In the Message Filtering section, choose the index-item events:

• index-item.deleted
• index-item.updated

Svix message filtering for index-item events

3

Save the endpoint

Save your endpoint configuration by choosing the Create button.

4

Test the configuration

Go back to the Emporix Management Dashboard and add a new product. After a few minutes, you should see the updated delivery statistics in Svix.

Svix delivery statistics after sending a test event