Webhooks в сервисе CARTPROTECTOR

Что это такое и зачем?

WebHooks – это способ уведомления сторонних приложений, CRM и т.д. о событиях, которые происходят в сервисе .

Для подключения Webhooks достаточно в основных настройках сайта на вкладке Настройки интеграции указать ссылку на обработчик событий Webhooks для вашего сайта.

Webhook event (событие) передается методом POST в виде массива данных, упакованных в строку JSON, в параметре event.

Структура события

Полная структура события, передаваемого webhook:

{
    timestamp: <int>,
    trackerId: <int>,
    visitorId: <string>,
    trackId: <string>,
    eventType: <string>,
    eventStage: <int|string>,
    contacts: {
        email: <string>
    },
    sentEmail: {
        senderEmail: <string>,
        senderName: <string>,
        replyToEmail: <string>,
        replyToName: <string>,
        receiverEmail: <string>,
        subject: <string>,
        html: <string>,
        text: <string>
    }
}
Обратите внимание

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

Где:

timestamp
Маркер времени возникновения события (unix timestamp).
trackerId
Идентификатор сайта в сервисе , на котором возникло это событие.
visitorId
Идентификатор посетителя в сервисе , с которым связано это событие.
trackId
Идентификатор трека отслеживания в сервисе , в рамках которого возникло это событие.
eventType
Тип события.
eventStage
Если на разных этапах возникают несколько однотипных событий, параметр определяет, на каком именно этапе возникло это событие.
contacts
Содержит переданные посетителем контакты для событий, связанных с передачей контактной информации посетителем в сервис .
  • email - email-адрес посетителя
sentEmail
Содержит параметры отосланного письма для событий, связанных с отправкой email-ов посетителям.
  • senderEmail - email-адрес, с которого отправлено письмо
  • senderName - имя отправителя
  • replyToEmail - email-адрес для ответа на письмо (автоматически будет подставлен в поле "Кому", если нажать "Ответить")
  • replyToName - имя адрессата для ответа на письмо
  • receiverEmail - email-адрес получателя (кому отправлено это письмо)
  • subject - тема письма
  • html - html содержание письма
  • text - альтернативное текстовое содержание письма

События

Получен контакт клиента

Событие contact-received отправляется после получения email-адреса в виджете.

Пример события:

{
    "timestamp" : "1508292652",
    "trackerId" : "9783",
    "visitorId" : "2a5d3fd3e096d6be73b883fd9826d916",
    "trackId" : "000097832a5d3fd3e096d6be73b883fd9826d916af6782d1",
    "eventType" : "contact-received",
    "contacts" : {
        "email" : "team@cartprotector.com"
    }
}

Письмо клиенту отправлено

Событие email-sent отправляется в момент отправки очередного письма посетителю.

Пример события, возникающего при отправке первого письма:

{
    "timestamp" : "1508292652",
    "trackerId" : "9783",
    "visitorId" : "2a5d3fd3e096d6be73b883fd9826d916",
    "trackId" : "000097832a5d3fd3e096d6be73b883fd9826d916af6782d1",
    "eventType" : "email-sent",
    "eventStage" : 1,
    "sentEmail" : {
        "senderEmail" : "team@cartprotector.com",
        "senderName": "Строй-маркет example.com",
        "replyToEmail": "sales@example.com",
        "replyToName": "Строй-маркет example.com",
        "receiverEmail": "customer1984@mail.ru",
        "subject": "Купон на скидку 5% от строй-маркета example.com",
        "html": "... HTML-код письма ...",
        "text": "... альтернативный текстовый вариант письма ..."
    }
}
Использование sentEmail.subject и sentEmail.text

Параметры sentEmail.subject и sentEmail.text удобно использовать для интеграции с CRM системами, т.к. они отображают тему и суть письма, но представлены в текстовом виде.

SDK

Библиотека для PHP

Установка:

php composer.phar require "cartprotector/webhooks: ^1.0"

Использование:

<?php

use CartProtector\Webhooks\Service\WebhookManager;

$event = WebhookManager::createWebhookEvent();
if ($event == 'contact-received') {
    echo 'New contact received: ' . $event->getContacts()->getEmail();
} elseif ($event == 'email-sent') {
    echo 'Email ' . $event->getEventStage() .
        ' sent to ' . $event->getSentEmail()->getReceiverEmail();
}
WebhookManager::createWebhookEvent($eventData = null)

Метод createWebhookEvent(), вызванный без опционального параметра автоматически получает его из $_POST['event'].