Webhooks

General description

Webhook is a method of tracking certain events in real time in the eSputnik system and notifying off-site web-applications about them. Figuratively it can be imagined as a subscription for certain events in the system, for example, canceling the subscription. Request-notifications are also named Webhooks.

Events that can be obtained using webhooks

As of today with the help of webhooks you can obtain changing the status of the letter:

delivered,
delivery error,
read,
recipient clicked the link,
recipient unsubscribed,
recipient complained about spam.

How to implement webhooks

You need to configure on your URL server, on which you want to obtain notifications.
Then it is necessary to write down this URL in eSputnik settings.
1. Authorize in the system, enter account settings, Laboratory section.
2. Activate Webhooks option.
3. Insert your URL in Website address field.
4. Save changes.

That is it for configuring.

The requests-notifications (webhooks) will be sent to indicated URL when activity occurs on sent email messages, for example, opening the letter, clicking the link from the letter, canceling the subscription, etc. The webhook will look like a JSON array, a test case with all possible status options:

[
  {
    "iid": "ffd3e1a7-a270-4e58-94de-5ac681c5c8e7",
    "contactId": 687266822,
    "activityStatus": "SUBSCRIPTION_CHANGED",
    "mediaType": email,
    "activityDateTime": "2019-09-26T14:45:18",
    "statusData": {
      "subscription": {
        "subscriptions": [
          "SMARTPHONES",
          "TABLETS",
          "LAPTOPS"
        ]
      }
    }
  },
  {
    "iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
    "contactId": 295953704,
    "email": "test@rambler.ru",
    "activityStatus": "DELIVERED",
    "mediaType": email,
    "messageId": 976440,
    "messageInstanceId": 1344540,
    "activityDateTime": "2018-03-01T13:31:52",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "hardBounce": false,
    "iid": "D5AF8EFC-2E8F-4BB5-B427-77D554B30E65",
    "contactId": 357885291,
    "sms": "380671234567",
    "activityStatus": "UNDELIVERED",
    "mediaType": sms,
    "activityDateTime": "2019-10-01T03:43:49",
    "statusDescription": "IM_NO_MONEY"
  },
  {
    "hardBounce": false,
    "iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
    "contactId": 295953704,
    "email": "test@rambler.ru",
    "activityStatus": "UNDELIVERED",
    "mediaType": email,
    "messageId": 976440,
    "messageInstanceId": 1344540,
    "activityDateTime": "2018-03-01T13:31:58",
    "statusDescription": "smtp;554 5.7.1 Spam message rejected; If this is not spam contact abuse",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
    "contactId": 318515138,
    "email": "test@gmail.com",
    "activityStatus": "READ",
    "mediaType": email,
    "messageId": 1235215,
    "messageInstanceId": 1622691,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T04:05:53",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
    "contactId": 371353431,
    "email": "test@gmail.com",
    "activityStatus": "UNSUBSCRIBED",
    "mediaType": email,
    "messageId": 1166457,
    "messageInstanceId": 1550164,
    "messageTag": "1521722870",
    "activityDateTime": "2018-05-15T09:56:40",
    "viewMessageLink": "https://123.esclick.me/test"
  },
  {
    "iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
    "contactId": 39781237,
    "email": "test@gmail.com",
    "activityStatus": "CLICKED",
    "mediaType": email,
    "messageId": 1242672,
    "messageInstanceId": 1630305,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T04:45:04",
    "viewMessageLink": "https://123.esclick.me/test",
    "clickEventLink": "https://test.ua/promo/"
  },
  {
    "iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
    "contactId": 351886894,
    "email": "test@mail.ru",
    "activityStatus": "SPAM",
    "mediaType": email,
    "messageId": 1242672,
    "messageInstanceId": 1630305,
    "messageTag": "1522397496",
    "activityDateTime": "2018-05-15T08:23:56",
    "viewMessageLink": "https://123.esclick.me/test"
  }
]

Each element of the array will include following parameters:

Parameter	Type	Description
contactId	int	Identifier of the contact.
email	string	Contact’s email.
activityStatus	string	DELIVERED - the message is delivered UNDELIVERED - the message is not delivered READ - the message is read UNSUBSCRIBED - contact canceled the subscription CLICKED - contact passed links in the message SPAM - contact complained about spam
messageId	int	Message identifier.
messageInstanceId	int	Identifier of message copy.
messageTag	string	Mark of the message.
activityDateTime	string	Date and time, when activity happened.
statusDescription	string	This field is returned only in case, if the status is UNDELIVERED, Contains the reason, why the message wasn’t delivered. It can be a response of the recipient’s server, system response about the impossibility to send a message, etc.
viewMessageLink	string	Contains link for the message
clickEventLink	string	Contains link, which contact clicked

Practical usage of webhooks

Given functionality is used for the actualization of information about contacts in a database on your side in real-time mode. For example, it allows working with urgent information from eSputnik system in your CRM. You can use this information for following purposes: for client database segmentation considering clients activity on mailings for analyses complex promotional campaigns, in which eSputnik is one of the used channels for creating backups of the database, completed with information from eSputnik. For the more vivid conception of possibilities scale, which are opened before you, let’s imagine the following situation. There is a phone call from your client to call-center with a question about sales campaign, indicated in the letter. Operator have questions: what sale is client talking about? What letter was sent today exactly to this client by the marketing department? This problem can be solved by sending CRM information about the activity of subscribers in real-time mode with the help of webhooks.