Webhooks for Tracking Activity

Webhooks allow you to track contact activity in the eSputnik 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:

  • 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.

📘

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

Open the Data export tab in your account settings, click the New data export button, and select Webhook.

New data export

Connection

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

Connection

Autentification (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.

Autentification

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.

Export activity statuses

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

Save settings

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

Active webhook

Settings Verification

The system will check the URL's availability using the GET request. If errors occur, your server may block our request for various reasons. You can determine the exact cause based on the server error code on your side.

If the check is successful, the setup is complete.

After that, perform any action in your eSputnik account — for example, send yourself an email. The POST request in JSON format with information about the latest activity will be sent to the specified URL.

For example, if a contact receives an email, opens it, and clicks a link, the system will sequentially send three requests with the statuses: DELIVERED, READ, and CLICKED.

If the webhook URL does not return the HTTP 200 response code, the POST request attempt is repeated with incremented intervals (1 minute, 2 minutes, 4 minutes, 8 minutes, and up to 1 request per hour). The following requests are postponed until the first one is successfully delivered, and then delivered in their sequence.

Webhook Deactivation

To deactivate the webhook, click the three-dot icon, select Deactivate webhook, and confirm the action.

Webhook deactivation

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.

Data Export Editing

List of Possible Parameters

ParameterTypeDescription
activityDateTimestringActivity date and time.
activityStatusstringActivity status:
SENT– the message is sent (for Mobile Push only)
DELIVERED – the message was delivered.
UNDELIVERED – the message was undelivered (statusDescription contains the reason).
READ – the message was read.
UNSUBSCRIBED – a contact unsubscribed from the broadcasting list.
CLICKED – a contact clicked links in the message.
SPAM – a contact reported spam.
SUBSCRIPTION_CHANGED – a contact changed the subscription category.
broadcastIdintBroadcast ID.
clickEventLinkstringContains the link clicked by a contact (when the status is CLICKED).
contactIdintContact ID.
emailstringContact Email.
externalCustomerIdstringA unique customer ID in the client’s system.
hardBounceboolThis field is returned only in case when the status is UNDELIVERED. The parameter informs that the contact is in the black list.

false – not in the black list at the moment of message delivery.
true – in the black list at the moment of message delivery.
iidstringService Parameter.
mediaTypestringMedia type (SMS, Email, Web Push, Viber, Mobile Push, AppInbox, Widget, In-App, Telegram).
messageIdintMessage ID.
messageInstanceIdintMessage instance ID.
messageLanguageCodestringIdentifier of the message language.
messageNamestringMessage name (empty for test emails).
messageTagstringMessage tag.
mobilepushstringMobile app subscriber token.
smsstringContact phone number.
sourceEventIdintSource event ID.
sourceEventKeystringSource event key.
sourceEventTypeKeystringSource event type key.
statusDataData array.
statusDescriptionstringThis field is returned only in the event when the status is UNDELIVERED. It contains the reason why the message has been undelivered. This may be a recipient server response, a system response saying that message delivery was not possible, and other similar reasons.
subscriptionData array.
subscriptionsarray of stringsSubscription category keys.
viberstringContact phone number.
viewMessageLinkstringContains the link to the message web version.
webpushstringWeb push subscriber token.
workflowBlockIdstringWorkflow block ID.
workflowIdintWorkflow ID.
workflowInstanceIduuidThe identifier of a particular workflow launch. Use it to group mailings within the launch of a workflow.

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

Bulk campaign:

[ { "broadcastId": 3459207, "messageName": "test", "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18", "contactId": 1967597908, "externalCustomerId": "789456512", "email": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8", "contactId": 889891911, "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92", "email": "test2@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4", "contactId": 1026901517, "email": "test3@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "hardBounce": false, "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18", "contactId": 1967597908, "externalCustomerId": "789456512", "email": "test1@yourdomain.com", "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", "statusData": {} } ]

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": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702524, "activityDateTime": "2023-09-14T08:30:50", "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P", "statusData": {} }, { "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": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702524, "activityDateTime": "2023-09-14T08:30:51", "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP", "statusData": {} }, { "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", "statusData": {} } ]

Alternative Methods for Tracking Activity Statuses

For comparison/alternative, the API method Get contacts activity is used.

It works by sending GET requests from your side, where you can specify a time interval (up to 3 months) and parameters (such as email, status, etc.).


Did this page help you?