---
updatedAt: 2026-04-24T10:23:33.000Z
agentTools:
  projectIndex: https://developer.reviews.io/llms.txt
---

# Add a review submitted Webhook

Creates a new webhook. The webhook will trigger when a review is submitted with a POST request containing the following body:

```json
{
    'id' : '(our unique identifer for the review)',
    'review_type' : '(company or product)',
    'order_id' : '(your reference for the reviewers purchase)',
    'rating' : '(1 to 5 star rating)',
    'comments' : '(review text)',
    'user' : {
        'name' : '(reviewers name)',
        'email_address' : '(reviewers email address)'
    },
    'product' : {
        'sku' : '(sku of product being reviewed, only included for product reviews)'
    }
}
```

The ID returned by this endpoint can later be used to remove the webhook using the [Remove a review submitted Webhook](https://developer.reviews.io/reference/a12d39f40cab062f41bf7c6daf807dff)  endpoint.

Webhooks can also be created as part of an Invitation Flow in the REVIEWS.io dashboard.

Additional data can be requested using the **includes** parameter which expects a comma separated list, the following values are accepted :-

| Includes            | Description                                                                           |
| ------------------- | ------------------------------------------------------------------------------------- |
| attribute\_customer | attribute data stored for the user                                                    |
| attribute\_company  | store\_review attribute data                                                          |
| attribute\_product  | product\_review attribute data                                                        |
| tags                | tags included against the review                                                      |
| product             | full details stored for the product for a product\_review                             |
| user                | general stats are generated for the user                                              |
| photo               | photos on the review appended with our asset url, includes active and inactive status |
| video               | videos on the review appended with our asset url, includes active and inactive status |

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "REVIEWS.io API",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://api.reviews.io",
      "description": "REVIEWS.io API"
    },
    {
      "url": "https://api.reviews.co.uk",
      "description": "REVIEWS.co.uk API"
    }
  ],
  "paths": {
    "/webhook/add": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Add a review submitted Webhook",
        "operationId": "2966f9313240bd3856bb4045dac3731f",
        "parameters": [
          {
            "$ref": "#/components/parameters/store"
          },
          {
            "$ref": "#/components/parameters/apikey"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/create_webhook"
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/webhook_created_response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "webhook": {
        "title": "Review webhook",
        "description": "Review webhook",
        "required": [
          "type",
          "url"
        ],
        "properties": {
          "type": {
            "description": "Type of review to be notified of",
            "enum": [
              "company_review",
              "positive_company_review",
              "negative_company_review",
              "product_review",
              "positive_product_review",
              "negative_product_review",
              "company_review_update",
              "positive_company_review_update",
              "negative_company_review_update",
              "product_review_update",
              "positive_product_review_update",
              "negative_product_review_update"
            ],
            "example": "product_review"
          },
          "url": {
            "description": "Webhook target url",
            "example": "https://api.domain.com/new-product-review"
          },
          "includes": {
            "description": "Allow additional data to be returned in webhooks",
            "example": "attribute_customer,attribute_company,attribute_product,tags,product,user,photo,video"
          }
        },
        "type": "object"
      },
      "webhook_created_response": {
        "title": "Webhook",
        "description": "Webhook",
        "properties": {
          "status": {
            "description": "Status",
            "type": "string",
            "example": "success"
          },
          "webhook": {
            "description": "Webhook ID",
            "type": "string",
            "example": "htv23P7M"
          }
        },
        "type": "object"
      }
    },
    "parameters": {
      "store": {
        "name": "store",
        "in": "query",
        "description": "Your REVIEWS.io public store key",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "apikey": {
        "name": "apikey",
        "in": "query",
        "description": "Your REVIEWS.io private api key",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "requestBodies": {
      "create_webhook": {
        "description": "",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/webhook"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Webhooks",
      "description": ""
    }
  ],
  "x-readme": {
    "explorer-enabled": false
  }
}
```