---
updatedAt: 2025-09-11T20:05:47.000Z
agentTools:
  projectIndex: https://docs.makaira.io/llms.txt
---

# Search Webhook

# What is a search webhook?

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

![](https://files.readme.io/c9ba5eb-image.png)

# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

* Search: <https://docs.makaira.io/reference/post-search>
* Search public: <https://docs.makaira.io/reference/post-search-public>
* Recommendation: <https://docs.makaira.io/reference/post-recommendation>
* Recommendation public: <https://docs.makaira.io/reference/post-recommendation-public>