About Webhooks

Introduction

Use webhooks to get notifications about events taking place in your Yotpo products.
You can use the notifications in integrated third-party apps, for example:

To collect data for data warehousing.
To integrate with other software or services, such as OMS, CRM, and billing.
To integrate with additional marketing apps.

How to use webhooks

When you subscribe 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 customer earned loyalty points. After subscribing to webhooks, you will be able to manage them using the endpoints listed below.

Loyalty webhook payloads that include a customer object may include customer.points_expire_at, described on each event's page (for example Points Earned). The same semantics apply to customer API responses when loyalty data is included.

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 Webhook events for every event name). 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.

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

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

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

Webhook request headers

Every event is sent as a POST with a JSON body and these headers:

Header	Description
`X-Yotpo-Webhooks-Event-Type`	The event name, for example `review_create` or `swell/points/earned`. Review events have no `topic` field in the body, so use this header to route them.
`X-Yotpo-Webhooks-Tenant-Type`	The kind of account the event belongs to: `store`.
`X-Yotpo-Webhooks-Tenant-Id`	Your store ID.
`WebhookMessageId`	A unique ID for the event.
`WebhookMessageIdPerTarget`	A unique ID for this delivery to this target. Use it to ignore duplicates (see below).

Ignoring duplicate events

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

Response time and retries

We recommend responding to events as soon as possible, with a 200 OK response.
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.