When subscribing to webhooks events (topics), Yotpo will send the information in a JSON-formatted payload to your specified destination. The webhook is triggered for every event that takes place from that time on. After subscribing to webhooks, you will be able to manage them using the endpoints listed below.

Upon subscribing to a webhook event (topic), your application has the ability to execute code in real-time following specific events in stores where your app is installed or for your app itself. This eliminates the need for regular API calls to check their status. For example, webhooks can prompt an action in your app when a customer subscribes to receive SMS Marketing, or when a merchant uninstalls your app in the Yotpo admin.

By leveraging webhooks, you can minimize the number of API calls, ensuring your apps are more streamlined and updated promptly.

App-level and Store-level webhooks

Each event is characterized by a tenant type that 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.

How to create and manage webhooks

When subscribing to webhooks, Yotpo will send the information in a JSON-formatted payload to your specified destination. The webhook is triggered for every event, for example, whenever a new customer subscribes to SMS marketing. After subscribing to webhooks, you will be able to manage them using the endpoints listed below.

To create a new webhook subscription (to one or more events), use the following endpoints, and in this order:

Create a webhook target. Specify the callback URL of your destination app that will receive incoming notifications. The endpoint returns a target ID.
Create a webhook filter. Specify all the events you want to include in this filter (see a list of available events below). The endpoint returns a filter ID.
Subscribe to your webhook. To activate your webhook and start getting notifications, you must specify the target and filter IDs you received from the webhook target and webhook filter.

🚧
Please note:
Make sure you are using the correct endpoints as there are different endpoints to use when subscribing to app-level webhooks and store-level webhooks

Webhook endpoints

Webhook targets

Your webhook target will be your callback URL. You can use your webhook target and webhook filter to create a subscription.

Create target - Create a webhook target
Retrieve targets - Retrieve a list of all of your webhook targets
Retrieve target by ID - Retrieve a webhook target using its Yotpo ID
Update target - Update a webhook target
Delete target - Delete a webhook target

👍
URL requirements

Use only secure URLs that start with HTTPS

URLs can have a maximum length of 2048 characters

URLs must conform to RFC 2396

Webhook filters

Your webhook filter lets you create a list of events to subscribe to. You can use your webhook target and webhook filter to create a subscription.

Create filter - Create a webhook filter
Retrieve filters - Retrieve a list of all of your webhook filters
Retrieve filter by ID - Retrieve a webhook filter using its Yotpo ID
Update filter - Update a webhook filter
Delete filter - Delete a webhook filter

Webhook subscriptions

Store-level webhook subscriptions

Your webhook subscription lets you subscribe to store events for the stores that installed your app and provide a target for the callback.

Create store subscription - Create a webhook subscription
Retrieve store subscriptions - Retrieve a list of all of your webhook subscriptions
Retrieve store subscription by ID - Retrieve a webhook subscription using its Yotpo ID
Update store subscription - Update a webhook subscription
Delete store subscription - Delete a webhook subscription

App-level webhook subscriptions

Your webhook subscription lets you subscribe to App events and provides a target for the callback.

Create app subscription - Create a webhook subscription
Retrieve app subscriptions - Retrieve a list of all of your webhook subscriptions
Retrieve app subscription by ID - Retrieve a webhook subscription using its Yotpo ID
Update app subscription - Update a webhook subscription
Delete app subscription - Delete a webhook subscription

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

Ignoring duplicate events

To avoid processing duplicate messages by the target, every event sent to the target URL includes a header with a WebhookMessageId.
Example: 'WebhookMessageId: 066c9f28-3e87-45d5-a67e-879d6090d989'

Response time and retries

We recommend responding to events as soon as possible, with a 200 OK response. We expect to get a 200 OK response within 5 seconds. If we do not receive the approval, we will try again.
If there is a disconnect, for example, due to network issues, we will retry sending messages. We will attempt a retry at least 10 times, using an exponential backoff retry.