Вебхуки для відстеження активності

Webhooks (укр. — вебхуки) — метод відстеження в режимі реального часу певних подій у системі eSputnik та сповіщення про них сторонніх URL.

В eSputnik є два способи для налаштування та використання вебхуків:

1. Додавання зовнішнього URL для аккаунту, щоб відслідковувати активності користувачів.
2. Налаштування кастомних запитів в сценаріях через спеціальний блок Webhook.

Вебхуки для відстежування активностей

Ця функціональність дозволяє в режимі реального часу отримувати інформацію про всі активності контактів. Дані надходитимуть регулярно на вказаний URL POST запитами, як описано нижче.

Для порівняння/альтернативи є метод API Get contacts activity. Він працює при надсиланні з вашого боку GET запитів, в яких можна вказувати інтервал часу (не більше 3 місяців) та параметри (email, статус тощо).

Сьогодні за допомогою вебхуків можна отримувати інформацію про всі активності користувача після відправлених повідомлень (всі медіаканали):

• доставлено;
• помилка доставлення;
• прочитано;
• одержувач перейшов за посиланням;
• одержувач відписався від розсилок;
• одержувач поскаржився на спам.

Як впровадити вебхуки?

Вам необхідно сконфігурувати на своєму сервері URL, на який ви бажаєте отримувати повідомлення — POST-запити у форматі JSON та обробляти дані щодо них.

Потім цей URL необхідно додати до налаштувань eSputnik. Для цього авторизуйтеся в системі, зайдіть до налаштувань акаунта, розділ «Лабораторія». Активуйте опцію «Webhooks» і вставте ваш URL у поле «Webhook адреса».

Далі почнеться миттєва перевірка URL-адреси GET-запитом. Якщо раптом виникнуть помилки, то, можливо, на вашому боці спрацює блокування нашого запиту з різних причин. Про точну причину можна дізнатися за кодом помилки сервера на вашому боці.

Система перевірить доступність URL-адреси. Якщо все відбулося успішно, то налаштування завершене.

Після цього здійсніть будь-яку дію в акаунті. Наприклад, надішліть собі листа. Протягом кількох хвилин за вказаною адресою буде відправлений POST-запит з інформацією про останні активності. POST-запити відправлятимуться в форматі JSON при виникненні активності користувачів (відправлення email, відкривання повідомлення, перехід тощо).

Якщо webhook URL не повертає код відповіді HTTP 200, то спроба POST-запиту буде повторюватися із зростаючими інтервалами (1 хвилина, 2 хвилини, 4 хвилини, 8 хвилин і так до одного запиту на годину). Наступні запити будуть відкладені до успішного відправлення першого, а потім також відправлятимуться послідовно.

Вебхук матиме вигляд масиву JSON, тестовий приклад з усіма можливими варіантами статусів:

[{
		"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"
				]
			}
		}
	},
	{
		"broadcastId": 2833914,
		"messageName": "promo",
		"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
		"contactId": 295953704,
		"email": "test@yourdomain.com",
		"activityStatus": "DELIVERED",
		"mediaType": "email",
		"messageId": 976440,
		"messageInstanceId": 1344540,
		"activityDateTime": "2018-03-01T13:31:52",
		"viewMessageLink": "https://123.esclick.me/test"
	},
	{
		"broadcastId": 2833915,
		"messageName": "promo",
		"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"
	},
	{
		"broadcastId": 2833914,
		"messageName": "promo",
		"hardBounce": false,
		"iid": "76662EBB-9FD4-4A6A-B1F8-2F594DF9B7B4",
		"contactId": 295953704,
		"email": "test@yourdomain.com",
		"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"
	},
	{
		"workflowId": 245460,
		"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
		"sourceEventKey": "1258810400",
		"sourceEventTypeKey": "subscribeFromApi",
		"iid": "0bb5e1dc-0d1b-4deb-948f-8cea4d8ef738",
		"contactId": 1258810400,
		"email": "test@gmail.com",
		"activityStatus": "READ",
		"mediaType": "email",
		"messageId": 1235215,
		"messageInstanceId": 1622691,
	  	"messageName": "promo",
		"messageTag": "1522397496",
		"activityDateTime": "2018-05-15T04:05:53",
		"viewMessageLink": "https://123.esclick.me/test"
	},
	{
		"workflowId": 245460,
		"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
		"sourceEventKey": "1258810400",
		"sourceEventTypeKey": "subscribeFromApi",
		"iid": "92227CB7-4EEF-4168-9EA5-43F3ED3559F8",
		"contactId": 1258810400,
		"email": "test@gmail.com",
		"activityStatus": "UNSUBSCRIBED",
		"mediaType": "email",
		"messageId": 1166457,
		"messageInstanceId": 1550164,
	  	"messageName": "promo",
		"messageTag": "1521722870",
		"activityDateTime": "2018-05-15T09:56:40",
		"viewMessageLink": "https://123.esclick.me/test"
	},
	{
		"workflowId": 245460,
		"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
		"sourceEventKey": "1258810400",
		"sourceEventTypeKey": "subscribeFromApi",
		"iid": "d08d1e15-ea92-4d5c-8dc9-6f750250a6ff",
		"contactId": 1258810400,
		"email": "test@gmail.com",
		"activityStatus": "CLICKED",
		"mediaType": "email",
		"messageId": 1242672,
		"messageInstanceId": 1630305,
	  	"messageName": "promo",
		"messageTag": "1522397496",
		"activityDateTime": "2018-05-15T04:45:04",
		"viewMessageLink": "https://123.esclick.me/test",
		"clickEventLink": "https://test.ua/promo/"
	},
	{
		"workflowId": 245460,
		"workflowBlockId": "e_e9e90420db06b64c157440cd60d0b73d",
		"sourceEventKey": "1258810400",
		"sourceEventTypeKey": "subscribeFromApi",
		"iid": "0ae4b6a3-59ad-426e-a40b-ce8f55bd40bc",
		"contactId": 1258810400,
		"email": "test@yahoo.com",
		"activityStatus": "SPAM",
		"mediaType": "email",
		"messageId": 1242672,
		"messageInstanceId": 1630305,
	  	"messageName": "promo",
		"messageTag": "1522397496",
		"activityDateTime": "2018-05-15T08:23:56",
		"viewMessageLink": "https://123.esclick.me/test"
	}
]

Можливі параметри:

Практичне застосування вебхуків

Цей функціонал дозволяє отримувати в режимі реального часу інформацію про всі активності контакту без запитів інформації з вашого боку. Інформація надходитиме регулярно на вказаний URL POST-запитами, як описано вище.

Для порівняння/альтернативи існує метод API Get contacts activity.

Він працює при відправленні з вашого боку GET-запитів, у яких можна вказувати інтервал часу (не більше 3 місяців) і параметрів (email, статус тощо).

Документація: https://docs.esputnik.com/reference/contactactivity-1