Вебхук для кликов

Что такое вебхук для кликов? #

Вебхук для кликов — это способ, которым Haskimail уведомляет ваше приложение о том, что уникальный получатель кликнул по отслеживаемой ссылке в вашем письме. Это может быть полезно в самых разных ситуациях: например, для определения эффективности ваших транзакционных писем (легко ли клиенты находят ссылку для сброса пароля? предпочитают ли они просматривать подтверждения заказов в личном кабинете?), или просто для целей аудита.

Вы также можете использовать API Сообщений, чтобы запрашивать (pull) данные о кликах, но с вебхуком Haskimail сам отправляет (push) вам эту информацию по мере ее поступления. Вебхук для кликов отправляет данные в ваше приложение в простом для разбора (парсинга) формате JSON.

Haskimail будет отправлять POST-запрос на ваш вебхук для каждого уникального клика по ссылке в письмах, отправленных в течение периода хранения (по умолчанию 45 дней, но его можно настроить в диапазоне от 7 до 365 дней). По истечении этого периода Haskimail не сможет определить уникальность клика и, следовательно, не будет отправлять событие на ваш вебхук для кликов в письмах, отправленных раньше установленного срока.

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

Например:

Вы отправляете одно письмо с отслеживаемой ссылкой Маше и Пете. Оба кликают по ссылке. Ваш сервер получит два вызова с уникальными данными вебхука. Однако, если Маша или Петя кликнут по этой же ссылке еще раз, ваш сервер не получит дополнительного события. Кроме того, если в вашем письме несколько ссылок, каждый клик по новой ссылке будет зарегистрирован как отдельное событие, и ваш вебхук получит еще один вызов с информацией о том, какая ссылка была нажата и каким получателем.

Для ссылок в письмах, которые старше вашего периода хранения, мы по-прежнему обеспечим перенаправление на исходный URL, но они не будут считаться уникальными, и поэтому событие вебхука отправлено не будет.

Примечание: Дата и время в поле ReceivedAt передаются в формате ISO 8601.

Настройка URL вебхука для кликов #

Через веб-интерфейс Haskimail

Войдите в аккаунт Haskimail, выберите нужный Сервер и Канал, а затем перейдите на вкладку «Вебхуки». Нажмите «Добавить вебхук», введите URL в поле «URL вебхука» и установите флажок напротив события «Клики» (CLICKED).

Через API

Вы можете настроить событие CLICKED с помощью API как при создании нового вебхука, так и при редактировании уже существующего.

Данные вебхука для кликов #

Пример полного JSON-документа, который будет отправлен POST-запросом на ваш URL вебхука, показан справа. A brief description of some of the more interesting fields is below:

Recipient — email-адрес получателя, который кликнул по ссылке.
Tag — тег доставки, который был использован при отправке сообщения.
Metadata— пользовательские метаданные, которые были добавлены в письмо.
OriginalLink — ссылка, по которой кликнул получатель в письме.
ClickLocation — указывает, где была нажата ссылка: в HTML- или текстовой версии письма.
ReceivedAt — временная метка, когда произошел клик.

Пример JSON данных вебхука

{
  "RecordType": "Click",
  "MessageStream": "outbound",
  "ClickLocation": "HTML",
  "Client": {
    "Name": "Chrome 35.0.1916.153",
    "Company": "Google",
    "Family": "Chrome"
  },
  "OS": {
    "Name": "OS X 10.7 Lion",
    "Company": "Apple Computer, Inc.",
    "Family": "OS X 10"
  },
  "Platform": "Desktop",
  "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
  "OriginalLink": "https://example.com",
  "Geo": {
    "CountryISOCode": "RS",
    "Country": "Serbia",
    "RegionISOCode": "VO",
    "Region": "Autonomna Pokrajina Vojvodina",
    "City": "Novi Sad",
    "Zip": "21000",
    "Coords": "45.2517,19.8369",
    "IP": "8.8.8.8"
  },
  "MessageID": "00000000-0000-0000-0000-000000000000",
  "Metadata" : {
    "a_key" : "a_value",
    "b_key": "b_value"
   },
  "ReceivedAt": "2017-10-25T15:21:11.9065619Z",
  "Tag": "welcome-email",
  "Recipient": "ivan@example.com"
}

Тестирование вебхука для кликов с помощью curl #

Если вы ведете разработку на локальной машине или у вас нет публичного URL для вашего API, вы можете использовать пример POST-запроса, показанный справа. Замените <your-url> на API-маршрут, который вы хотите использовать в качестве URL вашего вебхука. Этот curl-запрос позволит вам убедиться, что ваш URL может принимать запросы в том же JSON-формате, который будут использовать серверы Haskimail.

Пример вызова curl

curl <your-url> \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{ 
        "ClickLocation": "HTML", 
        "Client": { 
            "Name": "Chrome 35.0.1916.153", 
            "Company": "Google", 
            "Family": "Chrome" 
        }, 
        "OS": { 
            "Name": "OS X 10.7 Lion", 
            "Company": "Apple Computer, Inc.","Family": "OS X 10" 
        }, 
        "Platform": "Desktop",
        "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko)  Chrome/35.0.1916.153 Safari/537.36", 
        "OriginalLink": "https://example.com", 
        "Geo": { 
            "CountryISOCode": "RS", 
            "Country": "Serbia", 
            "RegionISOCode": "VO", 
            "Region": "Autonomna Pokrajina Vojvodina", 
            "City": "Novi Sad",
            "Zip": "21000",
            "Coords": "45.2517,19.8369",
            "IP": "127.0.0.1"
        }, 
        "MessageID": "00000000-0000-0000-0000-000000000000",
        "ReceivedAt": "2017-10-25T15:21:11.9065619Z",
        "Tag": "welcome-email",
        "Recipient": "ivan@example.com",
        "RecordType": "Click" 
      }'

Как можно использовать данные о кликах #

Существует множество способов использования данных, которые предоставляет вебхук для кликов:

Определять, когда и откуда получатель кликнул по ссылке. Это особенно полезно, когда данные отслеживания открытий недоступны.
Проводить A/B-тестирование эффективности макетов ваших транзакционных писем.
Деактивировать ссылку (например, для сброса пароля) после однократного использования.
Уведомлять пользователей о подозрительной активности практически в реальном времени, если клик зарегистрирован из местоположения, которое отличается от места их входа в систему.