---
updatedAt: 2026-10-29T08:22:22.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Create filter

Create a webhook filter. This webhook filter can be used with multiple webhook targets. An event type cannot be used twice in the same webhook filter. For every event name you can subscribe to, see [Webhook events](https://core-api.yotpo.com/docs/topics).

<Callout icon="👍" theme="okay">
  ### How to use this endpoint

  To see an example request, click **Examples** in the payload on the right.
</Callout>

> 📘 Use event names exactly as listed in [Webhook events](https://core-api.yotpo.com/docs/topics), for example `review_create` or `swell/points/earned`. Topic names aren't validated: a misspelled topic is saved, but the filter never matches an event.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Yotpo API V3",
    "description": "Yotpo API V3 endpoints on api.yotpo.com. Webhook events are defined separately, in webhooks.json.",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://api.yotpo.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-Yotpo-Token": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Yotpo-Token",
        "description": "Your Yotpo account access token. See [Authentication](https://core-api.yotpo.com/reference/yotpo-authentication) to learn how to generate your access token."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized. The access token is missing, invalid or expired. With an invalid or expired `X-Yotpo-Token` the body is plain text: generate a new token with [Generate access token](ref:yotpo-authentication). A request with an `Authorization` header and no `X-Yotpo-Token` gets `Bad token; invalid JSON` as JSON: send the token in `X-Yotpo-Token`. An `Authorization` header sent along with a valid `X-Yotpo-Token` is ignored.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string",
              "example": "unauthorized"
            }
          },
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Error message.",
                  "example": "Bad token; invalid JSON"
                }
              }
            },
            "examples": {
              "Authorization header without X-Yotpo-Token": {
                "value": "{\n  \"message\": \"Bad token; invalid JSON\"\n}"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden. The request has no `X-Yotpo-Token` header.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Error message.",
                  "example": "Forbidden"
                }
              }
            },
            "examples": {
              "Missing token": {
                "value": "{\n  \"message\": \"Forbidden\"\n}"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "X-Yotpo-Token": []
    }
  ],
  "paths": {
    "/core/v3/stores/{store_id}/webhooks/filters": {
      "post": {
        "summary": "Create filter",
        "description": "Create a webhook filter. This webhook filter can be used with multiple webhook targets. An event type cannot be used twice in the same webhook filter. For every event name you can subscribe to, see [Webhook events](https://core-api.yotpo.com/docs/topics).",
        "operationId": "create-filter",
        "parameters": [
          {
            "name": "store_id",
            "in": "path",
            "description": "The store ID (app_key)",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhook_filter": {
                    "type": "object",
                    "required": [
                      "events"
                    ],
                    "properties": {
                      "events": {
                        "type": "array",
                        "description": "The event topics this filter matches, for example `review_create` or `swell/points/earned`. See [Webhook events](https://core-api.yotpo.com/docs/topics) for the full list. Topic names aren't validated: a misspelled topic is saved but never matches.",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "description": "The events to include. See [Webhook events](https://core-api.yotpo.com/docs/topics) for every event name."
                  }
                },
                "required": [
                  "webhook_filter"
                ]
              },
              "examples": {
                "Create filter": {
                  "value": {
                    "webhook_filter": {
                      "events": [
                        "review_create",
                        "review_updated"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"webhook_filter\": {\n    \"yotpo_id\": 6792\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhook_filter": {
                      "type": "object",
                      "properties": {
                        "yotpo_id": {
                          "type": "integer",
                          "description": "The Yotpo ID of the new object.",
                          "example": 6792
                        }
                      },
                      "description": "The created filter."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Unexpected input": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"unexpected input: <reason>\"\n    }\n  ]\n}"
                  },
                  "Filter is missing a <property> definition": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"webhook filter is missing a <property> definition\"\n    }\n  ]\n}"
                  },
                  "Filter is missing <property> definition": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"webhook filter contains an invalid value for <property>: <error-description>\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "title": "Unexpected input",
                      "type": "object",
                      "properties": {
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "message": {
                                "type": "string",
                                "example": "unexpected input: <reason>",
                                "description": "What's wrong with the request, usually naming the missing or invalid field. Meant for logs; the wording can change, so don't parse it."
                              }
                            }
                          },
                          "description": "The validation errors. Usually one item."
                        }
                      }
                    },
                    {
                      "title": "Filter is missing a <property> definition",
                      "type": "object",
                      "properties": {
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "message": {
                                "type": "string",
                                "example": "webhook filter is missing a <property> definition",
                                "description": "What's wrong with the request, usually naming the missing or invalid field. Meant for logs; the wording can change, so don't parse it."
                              }
                            }
                          },
                          "description": "The validation errors. Usually one item."
                        }
                      }
                    },
                    {
                      "title": "Filter is missing <property> definition",
                      "type": "object",
                      "properties": {
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "message": {
                                "type": "string",
                                "example": "webhook filter contains an invalid value for <property>: <error-description>",
                                "description": "What's wrong with the request, usually naming the missing or invalid field. Meant for logs; the wording can change, so don't parse it."
                              }
                            }
                          },
                          "description": "The validation errors. Usually one item."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "409",
            "content": {
              "application/json": {
                "examples": {
                  "Filter already exists": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"webhook filter already exists\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "webhook filter already exists",
                            "description": "Says that an object with the same identifier already exists."
                          }
                        }
                      },
                      "description": "The errors. Usually one item."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "application/json": {
                "examples": {
                  "Unexpected error": {
                    "value": "{\n  \"errors\": [\n    {\n      \"message\": \"unexpected error, try again later\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "unexpected error, try again later",
                            "description": "A general error message. Retry with backoff."
                          }
                        }
                      },
                      "description": "The errors. Usually one item."
                    }
                  }
                }
              }
            }
          }
        },
        "x-internal": false
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "value": "application/json",
        "key": "Content-Type"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

# Sibling pages

* [Create target](https://docs.yotpo.com/reference/create-target.md)
* [Retrieve targets](https://docs.yotpo.com/reference/retrieve-targets.md)
* [Retrieve target by ID](https://docs.yotpo.com/reference/retrieve-target-by-id.md)
* [Update target](https://docs.yotpo.com/reference/update-target.md)
* [Delete target](https://docs.yotpo.com/reference/delete-target.md)
* [Retrieve filters](https://docs.yotpo.com/reference/retrieve-filters.md)
* [Retrieve filter by ID](https://docs.yotpo.com/reference/retrieve-filter-by-id.md)
* [Update filter](https://docs.yotpo.com/reference/update-filter.md)
* [Delete filter](https://docs.yotpo.com/reference/delete-filter.md)
* [Create subscription](https://docs.yotpo.com/reference/create-subscription.md)
* [Retrieve subscriptions](https://docs.yotpo.com/reference/retrieve-subscriptions.md)
* [Retrieve subscription by ID](https://docs.yotpo.com/reference/retrieve-subscription-by-id.md)
* [Update subscription](https://docs.yotpo.com/reference/update-subscription.md)
* [Delete subscription](https://docs.yotpo.com/reference/delete-subscription.md)