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 billing and CRM
- 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 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.
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
SMS & Email webhook events
The following webhook events are available:
SMS events
| Webhook event name | Trigger |
|---|---|
communication.sms.subscribed.v1 | Triggered when a user subscribes to SMS communications |
communication.sms.unsubscribed.v1 | Triggered when a user unsubscribes from SMS communications |
communication.sms.sent.v1 | Triggered when an SMS message is sent to a user |
communication.sms.clicked.v1 | Triggered when a user clicks a link in an SMS message |
{
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"phone": "+14155552671"
}
}
Email events
| Webhook event name | Trigger |
|---|---|
communication.email.subscribed.v1 | Triggered when a user subscribes to email communications |
communication.email.unsubscribed.v1 | Triggered when a user unsubscribes from email communications |
communication.email.list_update.v1 | Triggered when a user email list is updated |
communication.email.sent.v1 | Triggered when an email is sent to a user |
communication.email.delivered.v1 | Triggered when an email is successfully delivered to a subscriber's inbox |
communication.email.opened.v1 | Triggered when a user opens an email |
communication.email.clicked.v1 | Triggered when a user clicks a link in an email |
communication.email.bounced.v1 | Triggered when an email bounces |
{
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"phone": "+14155552671"
}
}
Loyalty & Referrals webhook events
For the full list of Loyalty & Referrals events and their structure, click here.
Ignoring duplicate events
To avoid processing duplicate messages by the target, every event sent to the target URL includes a header with an Eventld.
Example: 'eventid: 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.