Webhooks

Ustawienia

Po uruchomieniu systemu Webhooks FreshMail będzie wysłał na wybraną przez Ciebie bramkę URL informacje o zdarzeniach za pomocą żądań typu HTTP POST. Najczęstszym wykorzystaniem tego typu integracji jest monitorowanie zaangażowania odbiorców (kliknięcia oraz otwarcia emaili), synchronizacja wypisanych odbiorców, identyfikowanie odbiorców, którzy nie reagują na Twoje kampanie od wielu miesięcy lub tworzenie zaawansowanej analityki po Twojej stronie.

Konfiguracja

Aby skonfigurować mechanizm WebHooks należy zalogować się do Twojego konta we FreshMail'u, następnie przejść do Ustawienia -> Wtyczki i API -> Webhooks. Pojawi się formularz z pole URL. Po dodaniu URL do Twojej bramki możesz przetestować połączenie. Dla przykładu możemy założyć, że skrypt który chcesz aby był Twoją bramką umieściłeś pod adresem:

               http(s)://my-domain.com/api/freshmail/webhooks

Możliwe błędy

Jeśli zaraz po przetestowaniu połączenia za pomocą przycisku Testuj połączenie otrzymałeś komunikat o błędzie nie przejmuj się. Przecież jeszcze nie umieściłeś w tej lokalizacji żadnego skryptu.

Jeśli fizycznie nie ma tam jeszcze żadnej aplikacji, która mogłaby odpowiadać na nasze żądania po API to w komunikacie błędu pojawi się komunikat z biblioteki CURL w postaci:

Błąd requestu (curl) 404 - HTTP/1.1 404 Not Found

W takim wypadku musimy umieścić skrypt, który obsłuży nasze żądania. Jeśli umieścimy tam jakikolwiek skrypt to komunikat powinien się zmienić na:

Serwer odpowiedział lecz w niepoprawnym formacie

Oznacza to, że sktypt został znaleziony przez naszą aplikację poprawnie, ale niestety nie odpowiada danymi w poprawnym formacie.

Żądania testowe

W pierwszej kolejności należy sprawić, aby Twój skrypt był w stanie obsłużyć żądania testowe. Od nich zaczyna się cała komunikacja. Takie żądania możesz wysłać bezpośrednio z systemu FreshMail korzystając z przycisku Testuj połączenie lub przetestować je samemu np. za pomocą biblioteki CURL:

curl -X POST -d '{"test":"1"}' http(s)://my-domain.com/api/freshmail/webhooksie

FreshMal oczekuje zwrotki o kodzie 2xx HTTP w odpowiedzi na powyższe żądanie. Dodatkowo żądanie testowe musi zwrócić:

{"status":"ok"}

W ten sposób możesz przetestować całą komunikację testową. Jeśli ona dział poprawnie oznacza to, że nie ma żadnych problemów sieciowych w komunikacji pomiędzy serwerami FreshMaila a Twoim serwerem.

Zdarzenia

W produkcyjnej komunikacji będziesz otrzymywał żądania typu HTTP POST zawierające obiekt JSON z tablicą zawierającą kolejne zdarzenia. Każde pojedyncze żądanie może zawierać do 1000 zdarzeń i będzie wysyłane z możliwie najmniejszym opóźnieniem w stosunku do działań które odbiorca wykonuje na mailu.

Przykładowe żądanie HTTP POST

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    },{
        "campaign":"nsqqmsb52q",
        "email":"antonio@freshmail.com",
        "event":"open",
        "timestamp":1439889604,
        "attempt":1,
        "hash":"324f4075a6"
    },{
        "campaign":"nsqqmsb52q",
        "email":"samuel@freshmail.pl",
        "event":"open",
        "timestamp":1439892486,
        "attempt":1,
        "hash":"9d041d9ab3"
    }
]

Typy zdarzeń

Poniżej znajduje się lista wszystkich obsługiwanych przez FreshMaila zdarzeń:

Parametry domyślne zdarzeń

Każde zdarzenie posiada zestaw obligatoryjnych parametrów, które zawsze są przesyłane w tablicy ze zdarzeniem:

Identyfikator zdarzenia jest wykorzystywany do potwierdzenia odbioru.

UWAGA! Identyfikator NIE jest unikalny.

Jeśli dwa zdarzenia posiadają ten sam znacznik oznacza to, że niosą one dokładnie tą samą informację. Dla przykładu jeśli dany użytkownik otworzy daną kampanię 2 razy w przeciągu paru sekund to identyfikatory tego zdarzenia będą różne bo czas otwarcia będzie się różnił. Jeśli natomiast użytkownikowi udałoby się otworzyć maila 2 razy w tej samej sekundzie to identyfikatory dla tych dwóch zdarzeń będą identyczne, bo będą niosły dokładnie są samą informacje i z punktu FreshMail Webhooks będą nie rozróżnialne.

Parametry poszczególnych zdarzeń

Poniższa sekcja pokazuje przykład każdego typu zdarzenia. Pamiętaj, że każde zdarzenie jest pojedynczym elementem tablicy, która jest przesyłana w HTTP POST. Pola w zdarzeniach mogą pojawiać się w różnej koleności i nie są w żaden sposób sortowane.

Otwarcie

Zdarzenie mówiące o tym, że odbiorca otworzył wiadomość HTML.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"open",
    "timestamp":1439892486,
    "attempt":1,
    "hash":"event_id"
}

Kliknięcie

Zdarzenie mówiące o tym, że odbiorca kliknąl w link w mailu.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"click",
    "timestamp":1439971916,
    "attempt":1,
    "hash":"event_id",
    "url":"http://your-link.com/blog/"
}

Wypisanie

Zdarzenie mówiące o tym, że odbiorca skorzystał z linku rezygnacji w mailingu.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"unsubscribe",
    "timestamp":1439889404,
    "attempt":1,
    "hash":"event_id"
}

Potwierdzenie odbioru

Każde żądanie musi zostać potwierdzone, aby FreshMail wiedział, że zdarzenia zostały poprawnie przyjęte. W odpowiedzi oczekujemy kodu HTTP 200 oraz tablicy JSON z potwierdzonymi poszczególnymi zdarzeniami. Takie żądanie powinno zawierać tablicę z poszczególnymi zdarzeniami zawierającą:

Dla przykładu takie potwierdzenie może wyglądać jak w przykładzie poniżej. Żądanie wysyłane z FreshMail'a:

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    }
]

Poprawna odpowiedź (kod HTTP 200):

[
    {
      "hash":"97db930155",
      "status":true
    },{
      "hash":"ccec7ad7f1",
      "status":true
    }
]

Wprowadzenie

Mechanizm typu Webhooks jest prostym sposobem na otrzymywanie powiadomień w czasie rzeczywistym. Webhook jest mechanizmem podobny do API, ale komunikacja odbywa się w odwrotną stronę, czyli Ty definiujesz bramkę URL (callback URL) pod którą będziesz otrzymywać powiadomienia o różnych zdarzeniach w systemie. Każde zdarzenie będzie żądaniem HTTP POSTwysłanym pod wskazany przez Ciebie adres URL. W praktyce musisz napisać skrypt, który będzie w stanie obsłużyć żądania HTTP POST wysyłane od systemu FreshMail.

W tym momencie posiadamy jedną wersję mechanizmu Webhooks, który będzie cię powiadamiał za pomocą żądań HTTP POST o zdarzeniach, które miały miejsce w obrębie wysłanych przez Ciebie kampani mailingowych (np. otwarcie, kliknięcie).

Dla developerów

Działanie mechanizmu Webhooks wymaga zaimplementowania skryptu, który będzie w stanie odebrać dane oraz potwierdzić ich odbiór.

Wymagania

Pamiętaj, że skrypty, które stworzysz muszą być na tyle zoptymalizowane by mogły obsłużyć dużą liczbę żądań. Każde żądanie może zawierać nawet do 1000 zdarzeń i musi być obsłużone maksymalnie w przeciągu 5 sekund. Jeśli nie potrafisz obsłużyć naszych żądań odpowiednio szybko zalecamy odkładanie ich w jakichś mechanizmach po swojej stronie, a nam odpowiadać, że udało sie je przyjąć. Jeśli nie uda Ci się obsłużyc żądania w mniej niż 5 sekund po naszej stronie traktowane jest to jako błędna odpowiedź i dokładnie te same zdarzenia zostaną do Ciebie wysłane jeszcze raz w przyszłości.