App-level and store-level webhooks

Each event is characterized by a tenant type, which signifies the proprietor of the event data. Events that occur at the store level, such as the accumulation of loyalty points or the creation of a review, are linked with the store tenant type. Partners can subscribe to store events for the stores that have installed their apps.

Events pertaining to the disconnection of the application fall under the application tenant type. Only the application itself can subscribe to its own application events.

This structure ensures the accuracy and relevance of the event data.

When you subscribe to app-level webhooks, you need to insert only your application ID. The subscription is once per application ID. Use your app's client ID (the 32-character Application ID you got at registration, also used as client_id for tokens) as application_id in the path. The numeric app ID returns 403 Forbidden.
When you subscribe to store-level webhooks, you need to insert both the app ID and the specific store ID. You need to subscribe to each store separately.

Webhook request headers

Every event is sent as a POST with a JSON body and these headers. For how to use them, see About Webhooks.

Header	Description
`X-Yotpo-Webhooks-Event-Type`	The event name, for example `review_create` or `swell/points/earned`.
`X-Yotpo-Webhooks-Tenant-Type`	`store` for store events, `application` for app events.
`X-Yotpo-Webhooks-Tenant-Id`	The store ID (`app_key`) for store events, or your application ID for app events.
`WebhookMessageId`	A unique ID for the event.
`WebhookMessageIdPerTarget`	A unique ID for this delivery to this target. Use it to ignore duplicates.

Example: a review_create delivery. The body is shortened; see Review Created for the full payload.

curl "https://example.com/yotpo-webhooks" \
-X POST \
-H "content-type: application/json" \
-H "webhookmessageid: 9d13f1b2-f957-4ceb-a2be-3960fd4e3f2a" \
-H "webhookmessageidpertarget: adf35deb-06bf-4169-a647-84f97a419db2" \
-H "x-yotpo-webhooks-event-type: review_create" \
-H "x-yotpo-webhooks-tenant-id: YOUR_STORE_ID" \
-H "x-yotpo-webhooks-tenant-type: store" \
-d "{\"event\":\"review_create\",\"data\":{\"id\":12345,\"title\":\"Works great.\",\"score\":5,\"app_key\":\"YOUR_STORE_ID\",\"created_at\":\"2024-01-15T10:30:00Z\"}}"

Event names

To receive an event, add its name to events when you create a filter. Use the names exactly as shown: names aren't validated, so a misspelled name is saved but never matches. Each event's page lists its request headers, every body field and an example payload.

Reviews events (store level)

Review event bodies have no topic field. Read the event name from the X-Yotpo-Webhooks-Event-Type header.

Event name	Page	Sent when
`review_create`	Review Created	When a new review is created.
`review_updated`	Review Updated	When a review is published or unpublished, or when a reviewer verifies their email.
`review_request.eligible.on_fulfillment`	Review Request Eligible on Fulfillment	When an order becomes eligible for a review request after it is fulfilled.
`review_request.eligible.on_delivery`	Review Request Eligible on Delivery	When an order becomes eligible for a review request after it is delivered.

Loyalty & Referrals events (store level)

All 29 Loyalty events are listed in Introduction to Loyalty Events.

App events (app level)

Event name	Page	Sent when
`integrations.applications.disconnected.v3`	App Disconnected	When a merchant disconnects or uninstalls your app.

📘
More events coming soon!
Additional events for Yotpo's products will soon be added.