Integrate WiserReview with Ecommerce Site Builder

For whom: If you are building an ecommerce site builder and want to offer WiserReview as an integrated reviews solution for your merchant stores.

Integration Pattern

WiserReview workspaces are scoped per merchant. Your platform calls the verification endpoint once per merchant store to:

Receive widget iframe URLs and <div> embed snippets to inject into the merchant's storefront.

Begin receiving ongoing webhook events (rating_update, css_update) tagged with the merchant's wsid.

Prerequisite: Each merchant must already have a WiserReview workspace and API key (ak). Merchants obtain these by signing up at https://app.wiserreview.com. There is no parent/child workspace model — every merchant store is an independent workspace.

You may use one shared webhookUrl for all merchants and route incoming events by the wsid field, or use a per-merchant URL.

POST: https://api.wiserreview.com/api/custom/verify

Call this endpoint once per merchant to register their webhook URL and retrieve widget assets.

Request Headers

Header Name	Required	Description
x-wiserrw-api-key	Yes	The merchant's workspace API key. Used to authenticate and identify the calling workspace.

Request Body

Field Name	Required	Description
webhookUrl	Yes	The webhook URL where we will send the data for this merchant. Requests include the `x-wiserrw-api-key` header and a JSON object in the body.

Responses

200 — Success

{
  "status": "success",
  "msg": "API key verified successfully.",
  "data": {
    "wsid": "<workspace_id>",
    "ak": "<api_key>",
    "mainURL": "https://app.wiserreview.com/<wsid>/reviewWidget/main?id=<widget_id>?custauth=<JWT Token>",
    "mainWidgetDiv": "<div id='wiser_review_main' data-type='main' data-lgin='true' class='wiser_review wsr_main' data-platform='custom_main' data-pid='SET_YOUR_PRODUCT_ID_HERE' data-id='<widget_id>'></div>",
    "starRatingWidgetId": "https://app.wiserreview.com/<wsid>/reviewWidget/star_rating?id=<widget_id>?custauth=<JWT Token>",
    "starRatingWidgetDiv": "<div data-type='star_rating' data-platform='custom_star_rating' class='wiser_review wsr_rating' data-pid='SET_YOUR_PRODUCT_ID_HERE' data-id='<widget_id>'></div>",
    "nudgeWidgetId": "https://app.wiserreview.com/<wsid>/reviewWidget/carousel_product?id=<widget_id>?custauth=<JWT Token>",
    "nudgeWidgetDiv": "<div data-type='carousel_product' data-platform='custom_carousel_product' class='wiser_review wsr_carousel_product' data-pid='SET_YOUR_PRODUCT_ID_HERE' data-id='<widget_id>'></div>",
    "css": "<script>...</script>"
  }
}

Response Fields

Field	Description
wsid	The merchant's WiserReview workspace ID. Store this against the merchant in your platform — incoming webhook events use it to identify which merchant the event belongs to.
ak	The merchant's API key (echo of the header you sent).
mainURL	iframe URL for the main review widget. Embed on merchant product pages.
mainWidgetDiv	Ready-to-inject `<div>` for the main widget. Replace `SET_YOUR_PRODUCT_ID_HERE` with the merchant's product ID at render time.
starRatingWidgetId	iframe URL for the star-rating widget. (Despite the `Id` suffix, this is a URL.)
starRatingWidgetDiv	`<div>` snippet for the star-rating widget. Replace `SET_YOUR_PRODUCT_ID_HERE`.
nudgeWidgetId	iframe URL for the product-carousel ("nudge") widget. (Despite the `Id` suffix, this is a URL.)
nudgeWidgetDiv	`<div>` snippet for the carousel widget. Replace `SET_YOUR_PRODUCT_ID_HERE`.
css	A `<script>` string that injects WiserReview's star-rating CSS into the page `<head>`. Inject once per storefront page.

400 — Bad Request

{ "status": "error", "msg": "Webhook URL is required" }

403 — Forbidden

{ "status": "error", "msg": "Forbidden" }

Returned when the x-wiserrw-api-key does not match any workspace.

500 — Internal Server Error

{ "status": "error", "msg": "Internal Server Error" }

Response sent on webhook

WiserReview pushes events to the merchant's registered webhookUrl as POST requests with:

Header: x-wiserrw-api-key: <merchant_api_key>

Header: Content-Type: application/json

Body: JSON object — see event types below

Use the wsid field in the payload to route the event to the correct merchant in your system.

For star rating data update

{
  "wsid": "<workspace id>",
  "type": "rating_update",
  "data": [
    { "pid": "<product id>", "starHTML": "<rendered star HTML string>" }
  ]
}

For CSS update

{
  "wsid": "<workspace id>",
  "type": "css_update",
  "css": "<raw CSS string for star rating>"
}

Delivery semantics: Webhook delivery is fire-and-forget — there are no retries. If your endpoint returns non-2xx or times out, the event is dropped on the WiserReview side. Make your handler idempotent (keyed by wsid + pid for rating_update, by wsid for css_update) and surface delivery failures via your own monitoring.

API Verification Flow

Integrate WiserReview with Ecommerce Site Builder#

Integration Pattern#

POST: https://api.wiserreview.com/api/custom/verify#

Request Headers#

Request Body#

Responses#

200 — Success#

Response Fields#

400 — Bad Request#

403 — Forbidden#

500 — Internal Server Error#

Response sent on webhook#

For star rating data update#

For CSS update#