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 dispatch of an SMS, 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.
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 headers

Headers use key-value parameters that are sent as part of the webhook request.
A standard header contains a key-value pair that can be added to a webhook.

Yotpo’s webhooks include 4 types of headers:

X-Yotpo-Webhooks-Tenant-Type : The tenant type of the event (store or application)
X-Yotpo-Webhooks-Tenant-Id : The ID of the tenant - depending on the tenant, this field is either _store_id(_app_key) or application_id
WebhookMessageId : A unique ID for the event. This helps catch duplicate events
X-Yotpo-Webhooks-Event-Type: Specifies the event type that triggered the webhook, allowing quick identification of the event without parsing the payload.

Examples:

Below are examples of what the headers should look like when your webhook is received.

curl "https://mock.test.com" \
-X POST \
-H "content-length: 123" \
-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: communication.sms.subscribed.v1" \
-H "x-yotpo-webhooks-tenant-id: XxUcKDzVhizs3UE2qDWhvpsfkFPlfjj5XIfGsyxX" \
-H "x-yotpo-webhooks-tenant-type: store" \
-d "{\"sub_source\":\"api_call\",\"accepts_sms_marketing\":true,\"event_name\":\"communication.sms.subscribed.v1\",\"source\":\"api\",\"timestamp\":\"2024-04-28T08:17:39\",\"customer\":{\"phone\":\"+14155552671\",\"last_name\":\"Smith\",\"external_id\":\"7120233057516\",\"first_name\":\"Tom\",\"email\":\"tom.smith@hostname.com\"}}"

curl "https://mock.test.com" \
-X POST \
-H "content-length: 123" \
-H "content-type: application/json" \
-H "webhookmessageid: dca3102d-b0e1-4916-938e-eef8ae50d4eb" \
-H "webhookmessageidpertarget: 03518b67-9898-4d08-873f-5cf414bfa08d" \
-H "x-yotpo-webhooks-event-type: communication.email.subscribed.v1" \
-H "x-yotpo-webhooks-tenant-id: XxUcKDzVhizs3UE2qDWhopsfkFPlfjj5XIfGsyxX" \
-H "x-yotpo-webhooks-tenant-type: store" \
-d "{\"accepts_email_marketing\":true,\"sub_source\":\"api_call\",\"event_name\":\"communication.email.subscribed.v1\",\"source\":\"api\",\"timestamp\":\"2024-04-28T08:17:39\",\"customer\":{\"phone\":\"+14155552671\",\"last_name\":\"Smith\",\"external_id\":\"7130233057516\",\"first_name\":\"Tom\",\"email\":\"tom.smith@hostname.com\"}}"

UGC Reviews Events

Webhook event name	Trigger
`review_request.eligible.on_fulfillment`	Triggered when a review request becomes eligible after fulfillment.
`review_request.eligible.on_delivery`	Triggered when a review request becomes eligible after delivery.
`review_create`	Triggered when a new review is created in the Yotpo system.
`review_updated`	Triggered when: Review is published Review is unpublished (rejected) (For reviews created in the PDP Reviews Widget) Email is verified by the customer and the reviewer badge changes from anonymous to 'verified reviewer' Not triggered in these scenarios: Image is published / unpublished Review is tagged Review is pushed to a social channel Review is anonymized as a result of a DSR (GDPR) Review is deleted by Yotpo support (to fix import or another technical issue)

{
  "trigger": {
    "type": "fulfilled",
    "date": "2025-01-15T10:30:00Z"
  },
  "source_app_key": "abc123xyz789AppKeyExample",
  "order_id": "ORD-12345",
  "review_submission_url": "https://yotpo.com/go/aBcDeFg123",
  "shopper_profile": {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "locale": "en-US"
  },
  "products": [
    {
      "product_id": "prod_001",
      "variant_id": "var_001_blue_medium",
      "product_title": "Classic Cotton T-Shirt",
      "product_image_url": "https://cdn-yotpo-images-production.yotpo.com/Product/12345/67890/thumb.png"
    },
    {
      "product_id": "prod_002",
      "variant_id": "var_002_black",
      "product_title": "Premium Denim Jeans",
      "product_image_url": "https://cdn-yotpo-images-production.yotpo.com/Product/12346/67891/thumb.jpg"
    }
  ]
}

{
  "trigger": {
    "type": "delivered",
    "date": "2025-01-15T10:30:00Z"
  },
  "source_app_key": "abc123xyz789AppKeyExample",
  "order_id": "ORD-12345",
  "review_submission_url": "https://yotpo.com/go/aBcDeFg123",
  "shopper_profile": {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "locale": "en-US"
  },
  "products": [
    {
      "product_id": "prod_001",
      "variant_id": "var_001_blue_medium",
      "product_title": "Classic Cotton T-Shirt",
      "product_image_url": "https://cdn-yotpo-images-production.yotpo.com/Product/12345/67890/thumb.png"
    },
    {
      "product_id": "prod_002",
      "variant_id": "var_002_black",
      "product_title": "Premium Denim Jeans",
      "product_image_url": "https://cdn-yotpo-images-production.yotpo.com/Product/12346/67891/thumb.jpg"
    }
  ]
}

{
  "event": "review_create",
  "data": {
    "id": 12345,
    "source_app_key": null,
    "title": "Works great.",
    "reviewer_display_name": "John Doe",
    "content": "Works great.",
    "user_id": 1001,
    "score": 5,
    "deleted": false,
    "app_key": "au70vrn8Z2qkReVcRhiyJalGu80ekKfli0wXnXQg",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z",
    "new": false,
    "user_type": "User",
    "verified_buyer": true,
    "archived": false,
    "shop_owner": false,
    "twitter_pushed": 0,
    "facebook_pushed": 0,
    "review_source_type_id": 4,
    "votes_up": 0,
    "votes_down": 0,
    "review_type_id": 1,
    "source_review_id": null,
    "sentiment": null,
    "escalated": false,
    "customer_email": "customer@example.com",
    "order_id": 67890,
    "external_order_id": "ORDER-12345",
    "external_product_id": "PROD-67890",
    "product_title": "Premium Wireless Headphones",
    "language": "",
    "custom_review_form": [
      {
        "question": "Pets Name",
        "answer": "Max, Bella and Luna"
      }
    ]
  }
}

{
  "event": "review_updated",
  "data": {
    "id": 12345,
    "source_app_key": null,
    "title": "Works great.",
    "reviewer_display_name": "John Doe",
    "content": "Works great.",
    "user_id": 1001,
    "score": 5,
    "deleted": false,
    "app_key": "au70vrn8Z2qkReVcRhiyJalGu80ekKfli0wXnXQg",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z",
    "new": false,
    "user_type": "User",
    "verified_buyer": true,
    "archived": false,
    "shop_owner": false,
    "twitter_pushed": 0,
    "facebook_pushed": 0,
    "review_source_type_id": 4,
    "votes_up": 0,
    "votes_down": 0,
    "review_type_id": 1,
    "source_review_id": null,
    "sentiment": null,
    "escalated": false,
    "customer_email": "customer@example.com",
    "order_id": 67890,
    "external_order_id": "ORDER-12345",
    "external_product_id": "PROD-67890",
    "product_title": "Premium Wireless Headphones",
    "language": "",
    "custom_review_form": [
      {
        "question": "Pets Name",
        "answer": "Max, Bella and Luna"
      }
    ]
  }
}

Yotpo SMS & Email events

The following webhook events are available:

SMS events

Webhook event name (topic)	Trigger	Tenant type	Tenant ID
`communication.sms.subscribed.v1`	Triggered when a user subscribes to SMS communications	Store	store_id
`communication.sms.unsubscribed.v1`	Triggered when a user unsubscribes from SMS communications	Store	store_id
`communication.sms.sent.v1`	Triggered when an SMS message is sent to a user	Store	store_id
`communication.sms.clicked.v1`	Triggered when a user clicks a link in an SMS message	Store	store_id

{
  "event_name": "communication.sms.subscribed.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source": "api",
  "sub_source": "rndm_app",
  "accepts_sms_marketing": true,
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.sms.unsubscribed.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source": "api",
  "accepts_sms_marketing": false,
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.sms.sent.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "part_of_flow",
  "flow_id": 1019753,
  "campaign_id": null,
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.sms.clicked.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "part_of_campaign",
  "campaign_id": null,
  "flow_id": 1411137,
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671" 
  }
}

Email events

Webhook event name (topic)	Trigger	Tenant type	Tenant ID
`communication.email.subscribed.v1`	Triggered when a user subscribes to email communications	Store	store_id
`communication.email.unsubscribed.v1`	Triggered when a user unsubscribes from email communications	Store	store_id
`communication.email.list_update.v1`	Triggered when a user email list is updated	Store	store_id
`communication.email.sent.v1`	Triggered when an email is sent to a subscriber	Store	store_id
`communication.email.delivered.v1`	Triggered when an email is successfully delivered to a subscriber's inbox	Store	store_id
`communication.email.opened.v1`	Triggered when a user opens an email	Store	store_id
`communication.email.clicked.v1`	Triggered when a user clicks a link in an email	Store	store_id
`communication.email.bounced.v1`	Triggered when an email bounces	Store	store_id

{
  "event_name": "communication.email.subscribed.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source": "api",
  "sub_source": "yotpo",
  "accepts_email_marketing": true,
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671" 
  }
}

{
  "event_name": "communication.email.unsubscribed.v1",
  "timestamp": "2024-01-15T11:57:54",
  "accepts_email_marketing": false,
  "source_name": "rndm_campaigns",
  "source_id": "Loyalty Anniversary",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.list_update.v1",
  "timestamp": "2024-01-15T11:57:54",
  "list_id": "2822364",
  "action": "remove",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.sent.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "communication_flows",
  "source_id": "2822364",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.delivered.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "communication_flows",
  "source_id": "2822364",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.opened.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "communication_campaigns",
  "source_id": "2822364",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.clicked.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "communication_campaigns",
  "source_id": "2822364",
  "clicked_url": "https://testing.com/homepage?utm_campaign=yotpo",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

{
  "event_name": "communication.email.bounced.v1",
  "timestamp": "2024-01-15T11:57:54",
  "source_name": "communication_campaigns",
  "source_id": "2822364",
  "customer": {
    "external_id": 7144482046187,
    "first_name": "Tom",
    "last_name": "Smith",
    "email": "tom.smith@hostname.com",
    "phone": "+14155552671"
  }
}

App uninstall

Webhook event name (topic)	Trigger	Tenant type	Tenant ID
integrations.applications.disconnected.v3	Triggered when a merchant clicks on the "disconnect" button within the integration page in Yotpo or after they click uninstall within your product and you delete the access token using this endpoint.	application	application_id

{
  "topic": "integrations.applications.disconnected.v3",
  "name": "Application disconnected",
  "store": "STORE_APP_KEY",
  "product_lines": "[Reviews]"
}

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