Webhooks to Follow up Activities

This functionality allows receiving information about all the activities of your contacts in real-time. The information is delivered as scheduled to the specified URL using POST requests as explained below.

For comparison/alternative, there is eSputnik Public API. It is triggered when GET requests are sent from your side. Time intervals (3 months maximum) and parameters (email, status, and others) can be specified in the requests.

Using webhooks, you can receive information about events in all media channels:

delivered
delivery error
read
the recipient followed the link
the recipient unsubscribed
the recipient reported spam
messages are sent in any messaging channel
subscriptions, unique views, conversion for widgets.

How to Configure Webhooks for Your Account

Configure URL on the server where you want to receive notifications and POST requests in JSON format.

Indicate that URL address in eSputnik settings. To do that:

Click the caret next to your account name.
Choose Settings.
Choose the Laboratory item in the menu on the left side.

Enable the Webhooks slide button.
Click the caret of the Webhooks section.
Type in/paste your URL address into the Webhook address field.
Click the Save button.

Upon saving, a GET request is sent by the system to the URL address for testing. If an error is returned, then probably your server has blocked our request. The actual cause can be determined from the server error code. If the test has passed successfully, then the setting-up is complete.

After that, perform any action in your account. For example, send yourself an email message. In several minutes, a POST request is sent to the specified address with the information about the latest actions.

POST requests are sent in JSON format in case of any actions by users (sent email, opened message, click-through, or other).

If the webhook URL does not return the HTTP 200 response code then the attempt of the POST request 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 successful delivery of the first one and then they are delivered in their sequence.

List of Possible Parameters

Parameter	Type	Description
activityDateTime	string	Activity date and time
activityStatus	string	Activity status: `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.
broadcastId	int	Broadcast ID
clickEventLink	string	Contains the link clicked by a contact (when the status is `CLICKED`)
contactId	int	Contact ID
email	string	Contact Email
externalCustomerId	string	An unique customer ID in client’s system
hardBounce	bool	This 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.
iid	string	Service Parameter
mediaType	string	Media type (SMS, Email, Web Push, Viber, Mobile Push, AppInbox, Widget, In-App, Telegram)
messageId	int	Message ID
messageInstanceId	int	Message instance ID
messageName	string	Message name (empty for test emails)
messageTag	string	Message tag
mobilepush	string	Mobile app subscriber token
sms	string	Contact phone number
sourceEventId	int	Source event ID
sourceEventKey	string	Source event key
sourceEventTypeKey	string	Source event type key
statusData		Data array
statusDescription	string	This 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.
subscription		Data array
subscriptions	array of strings	Subscription category keys
viber	string	Contact phone number
viewMessageLink	string	Contains the link to the message web-version
webpush	string	Web push subscriber token
workflowBlockId	string	Workflow block ID
workflowId	int	Workflow ID
workflowInstanceId	uuid	The identifier of a particular workflow launch. Use it to group mailings within the launch of a workflow

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

Bulk campaign:

[
  {
    "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",
    "statusData": {}
  },
  {
    "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",
    "statusData": {}
  },
  {
    "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",
    "statusData": {}
  },
  {
    "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",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": {}
  }
]