Webhooks for Tracking Activity

Webhooks allow you to track contact activity in the Yespo in real time and automatically send notifications about each event to a specified client URL

Webhooks are configured by adding an external URL to your account. After that, you will automatically receive data about contact actions across various media channels via POST requests.

The system sends requests to your server whenever one of the following events occurs:

• Sent — the message sent to the contact (for Mobile Push only).
• Delivered — the message was delivered to the contact.
• Undelivered — the message could not be delivered.
• Read — the contact opened the message.
• Unsubscribed — the contact unsubscribed from the campaign.
• Clicked — the contact clicked on a link in the message.
• Spam — the message was marked as spam.
• Subscription changed — the contact changed their subscription category.

📘

Note

Before setting up webhooks, you need to configure an URL on your server where you want to receive messages — POST requests in JSON format — and process the data accordingly.

Creating Data Export

1. Open the Data export tab in your account settings.

2. Click the New data export button, and select Webhook.

Connection

Add a Webhook name and specify the Webhook URL you previously set up on your server.

Authentication (optional)

If authentication is enabled on your server, enter the login and password that your server requires to accept requests. Enable the Authentication toggle and fill in the corresponding fields.

Headers

Webhook headers allow you to pass additional information along with the request. They help quickly identify where the data came from, what it is used for, verify security, and more. This simplifies working with integrations and makes the integrations more reliable.

1. Click + Add header.

📘

Maximum number — 5.

2. Enter Key and Value.

All specified headers will be automatically added to webhook requests.

Export Activity Statuses

By default, all activity statuses are selected for tracking. You can modify this list by deselecting the checkboxes following to the statuses you don't want to track.

📘

Note

If some delivery statuses seem to be missing from your webhook data, check which channels are enabled for the webhook — status availability is channel-dependent, and not every status is generated for every channel. For example, SENT is documented above as available for the Mobile Push channel only.

A webhook can also be limited to specific media channels — for example, to receive statuses for mobile pushes only. This is configured on request: contact support at [email protected].

After setting up the data export via webhook, click the Save button.

The webhook will be active, and data will be sent in real-time to the specified URL.

Webhook Integration Testing

After configuring a webhook, you can verify its operation without triggering a real event.

1. Click Send test on the Data export via Webhook tab.

2. In the Test an integration window, a test request will open. It contains a demo array with several objects — an example of how the system generates webhooks for different channels.

You can manually modify the request body to test how your handler processes different data formats.

For example, change field values, remove or add array elements, etc.

All defined headers will be included in the test request if they were configured.

3. Click Submit.

4. The system immediately sends a test POST request to the specified webhook URL and displays the test result:

• if the server successfully accepts the request, a green banner appears with a collapsed details section;

• if the server returns an error (for example, 403) — a red banner appears with the response code and expanded details for analysis.

You can copy the request and response details to the clipboard.

After testing:

• click Save and close if the test was successful and the webhook works correctly;
• if an error occurred — click Retry; or click Close, make adjustments to the configuration, and send the test request again.

Deactivating / Deleting Webhooks

To deactivate or delete the webhook, click the three-dot icon, select the desired option, and confirm the action.

📘

Note

Deactivation suspends the sending of requests, but the webhook remains saved in the system and can be reactivated later.

Data Export Editing

To change the settings, click on the webhook name, edit the data, and save the settings.

List of Possible Parameters

Below are webhook test examples as a JSON array with all possible status options.

Broadcast:

[
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4",
    "contactId": 1026901517,
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "hardBounce": false,
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "UNDELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:07",
    "statusDescription": "5.1.2 (bad destination system: no such domain)",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  }
]

Triggered campaign:

[
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_05cae26d9ae85e1eb40ed34765f9c7be",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "019b7450-52d9-11ee-85c4-959256ea468c",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:50",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_527e1f819b41bd379d75ebbe3392b879",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "01777190-52d9-11ee-917a-ef6e91bfc7c3",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:51",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_be178ec8aacbf249d8bb736e9df9fd0d",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "hardBounce": false,
    "iid": "01a86ca0-52d9-11ee-85c4-959256ea468c",
    "contactId": 706515632,
    "sms": "380956490955",
    "mediaType": "viber",
    "activityStatus": "UNDELIVERED",
    "messageId": 3213684,
    "messageInstanceId": 4696769,
    "messageTag": "tag2,tag,test",
    "activityDateTime": "2023-09-14T08:30:51",
    "statusDescription": "401: null"
  }
]

Troubleshooting

Duplicate Events from WooCommerce

The WooCommerce plugin can fire the same PurchasedItems event twice for one order — once when the order is placed, and again if the customer reloads the success page after checkout. Yespo deduplicates orders by the order's key fields (such as externalOrderId); if a duplicate with the same key arrives, it is not recorded again. If you're building your own webhook consumer for order events, apply the same deduplication logic on your side using externalOrderId (or an equivalent idempotency key) to avoid double-counting.

See Installing the WooCommerce Plugin for setup details.

Event Deduplication Window

Events with an identical update body are deduplicated only within a 1-minute window — if the same event body arrives again after that window, it's processed as a new event. Events aren't deduplicated by timestamp alone.

Tags and Subject on Manually-Sent Messages

Tags on emails sent via the API are supported (e.g. via the tags array in the Send email message resource, v1/message/email) — the tags are returned in activity events and webhooks and let you identify which email an event belongs to. If they're missing from webhook activity data, check that your integration is actually sending the tags field correctly. The email subject is not passed in events. It is retrievable via the contactmessages method, but only for emails composed in the system, not raw HTML sent directly via the API.

Alternative Methods for Tracking Activity Statuses

Yespo offers three ways to get activity data into your own systems — pick based on how you plan to use the data:

📘

Note

The account UI (contact card) only stores the last open and click dates per contact, not the full history of opens/clicks. If you need the first open/click date or a full timeline, use webhooks (to build a full activity log as events happen) or the API/BigQuery methods above.

The Get contacts activity API is enabled on request — contact support to activate it for your account. Once enabled, it supports filtering by contact, for example an email parameter, in addition to status and time interval.