About Webhooks

Introduction

Webhooks send you Yotpo events as they happen, so you don't have to poll. For example:

Send a thank-you email when a customer earns points or leaves a review.
Keep a data warehouse, CRM, OMS or billing system in sync.
Trigger flows in other marketing apps.

Each event is a JSON POST to an HTTPS URL you choose. For every event name and payload, see Webhook events.

How to subscribe

Create three objects, in this order:

A target: the HTTPS URL that receives events. Create target returns a target ID.
A filter: the events you want. Use event names exactly as listed in Webhook events. Create filter returns a filter ID.
A subscription: connects the target and the filter and starts delivery. Create subscription takes both IDs.

Loyalty event 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.

Webhook endpoints

Targets

👍
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

Filters

Subscriptions

For app partners

Partner apps use the same three steps, with the app-level endpoints under /core/v3/applications/{application_id}/... and the per-store token each merchant's install gives you.

application_id: your app's client ID, the 32-character Application ID you got when you registered your app. The numeric app ID returns 403 Forbidden.
Targets and filters: create them once for your app with Create target and Create filter.
Store events (reviews, loyalty): create a store subscription for each store that installed your app. See Store-level webhooks.
App events: create one app subscription for your app. Today the only app event is App Disconnected, sent when a merchant disconnects or uninstalls your app. See App-level webhooks.

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` 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 (see below).

Ignoring duplicate events

Every delivery carries a WebhookMessageIdPerTarget header, for example WebhookMessageIdPerTarget: 066c9f28-3e87-45d5-a67e-879d6090d989. If you've already processed a message with that ID, ignore it.

Response time and retries

Respond with 200 OK as soon as you receive the event, and do the work afterwards. If Yotpo doesn't get a 200 (for example because of a network problem), it retries at least 10 times with exponential backoff.