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

  1. You need to configure on your URL server, on which you want to obtain notifications. 
  2. Then it is necessary to write down this URL in eSputnik settings. For this authorize in the system, enter account settings, Laboratory section. Activate Webhooks option and insert your URL in Website address field.
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. Webhook will be given as an events array. 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

Activity status

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.