Search Webhook

What is a search webhook?

Search webhook provides a way for you to adjust the search/recommendation request query as you desire.

What kind of webhook do we have?

Pre-search Hook

This hook is usable for both search and recommendation.

This hook allows you to adjust the search/recommendation query before the Original query is executed, Makaira will then execute the adjusted query and evaluate the result.

  • If the request fails or the search/recommendation result is empty, the original query will be used to execute the request again.
  • If the request succeeds and the search/recommendation result is not empty, skip the original query and proceed to the next step.

What will be sent to the hook URL?

For this hook, the original request body that is sent to the search and recommendation API will be forwarded.

Example request body:

{
  "searchPhrase": "shirt",
  "isSearch": true,
  "enableAggregations": true,
  "sorting": {},
  "constraints": {
    "query.language": "de",
    "query.shop_id": 1
  },
  "aggregations": {
  },
  "count": 100,
  "offset": 0,
  "fields": []
}

Post-search Hook

This hook is usable for both search and recommendation.

This hook allows you to adjust the search or recommendation query after the Original query is executed.

What will be sent to the hook URL?

For this hook, the original request body that is sent to the search and recommendation API and the original result of the request(see example bellow) will be forwarded.

Example request body:

{
  "searchPhrase": "shirt",
  "isSearch": true,
  "enableAggregations": true,
  "sorting": {},
  "constraints": {
    "query.language": "de",
    "query.shop_id": 1
  },
  "aggregations": {
  },
  "count": 100,
  "offset": 0,
  "fields": [],
  "originalResult": {
    "suggestion": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "product": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "bundle": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "category": {
      "items": [],
      "count": 2,
      "total": 2,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "links": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "manufacturer": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "page": {
      "items": [],
      "count": 0,
      "total": 0,
      "offset": 0,
      "aggregations": [],
      "additionalData": []
    },
    "searchredirect": {
      "items": [],
      "count": 0
    },
    "snippets": {},
    "banners": [],
    "experiments": []
  }
}

Modify result hook

This hook is usable for recommendation only.

This hook allows you to adjust the final result of the recommendation to add or remove some specific products from the recommendation result.

What will be sent to the hook URL?

For this hook, the result of the recommendation API will be sent to the hook URL.

Example request body:

{
  "items": [
    {
      "id": "b56764137ca959da9541bb28c1987d6c",
      "fields": {
        "ispseudo": false,
        "title": "Kite NBK REBEL 2010",
        "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/nkb_rebel_2010_1.jpg",
        "id": "b56764137ca959da9541bb28c1987d6c",
        "makaira-product": [
          {
            "ispseudo": true,
            "title": "Kite NBK REBEL 2010",
            "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/nkb_rebel_2010_1.jpg",
            "id": "d7758412ad714f41194bb846b8c30e90"
          }
        ],
        "_score": 2
      }
    },
    {
      "id": "b5685a5230f5050475f214b4bb0e239b",
      "fields": {
        "ispseudo": false,
        "title": "Bindung LIQUID FORCE INDEX BOOT 2010",
        "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/liquid_force_index_boot_2010_1.jpg",
        "id": "b5685a5230f5050475f214b4bb0e239b",
        "makaira-product": [
          {
            "ispseudo": true,
            "title": "Bindung LIQUID FORCE INDEX BOOT 2010",
            "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/liquid_force_index_boot_2010_1.jpg",
            "id": "e108b8c31e0da553dc0fd954ba67d922"
          }
        ],
        "_score": 2
      }
    },
    {
      "id": "d861ad687c60820255dbf8f88516f24d",
      "fields": {
        "ispseudo": false,
        "title": "Pumpe CABRINHA INFLATION 2011",
        "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/cabrinha_inflation_pump_1.jpg",
        "id": "d861ad687c60820255dbf8f88516f24d",
        "makaira-product": [
          {
            "ispseudo": true,
            "title": "Pumpe CABRINHA INFLATION 2011",
            "picture_url_main": "https://example-shop.makaira.io/oxid6/out/pictures/master/product/1/cabrinha_inflation_pump_1.jpg",
            "id": "c03635f31997bac953f0d74c9bb5d2aa"
          }
        ],
        "_score": 2
      }
    }
  ],
  "count": 3,
  "total": {
    "value": 3,
    "relation": "eq"
  },
  "offset": null,
  "aggregations": null,
  "additionalData": []
}

How to create a Search Query Hook?

Please refer to this API docs for more detail: https://docs.makaira.io/reference/post_search-query-hook

How to skip the search query hook?

You can skip the search query hook(the original result will be returned) by setting the enableHook parameter to false in the request body as mentioned in the API docs: