Вебхуки (Webhooks)

Webhooks (рус. вебхуки) – это пользовательские обратные запросы по HTTP. Обычно их отработка связана с каким-либо событием, например, прочтением письма или запуском приветственной серии. Вебхуки считаются удобным инструментом для отслеживания событий в реальном времени: как только событие наступает, на внешний URL отправляется запрос.

В eSputnik есть два варианта для настройки и использования вебхуков:

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

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

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

Для сравнения/альтернативы есть метод API Get contacts activity. Он работает при отправке с вашей стороны GET запросов, в которых можно указывать интервал времени (не более 3 месяцев) и параметры (email, статус и т. д.).

При помощи вебхуков вы будете получать информацию обо всех активностях пользователя после отправленных в любом канале сообщений:

• доставлено;
• ошибка доставки;
• прочитано;
• получатель перешел по ссылке;
• получатель отписался от рассылок;
• получатель пожаловался на спам.

Как подключить вебхуки для аккаунта

Сконфигурируйте на своем сервере URL, на который вы хотите получать уведомления, POST запросы в формате JSON.

Затем этот URL внесите в настройки eSputnik. Для этого авторизуйтесь в системе, зайдите в настройки аккаунта → раздел “Лаборатория”. Активируйте опцию “Вебхуки” и вставьте ваш 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"
	}
]