webhooki e-mail

Webhooki e-mail informują system docelowy o zdarzeniach związanych z wysyłką, np. otwarciu lub kliknięciu.

Webhook e-mail jako powiadomienie HTTP

Webhook e-mail to mechanizm przekazywania informacji o zdarzeniu związanym z wiadomością elektroniczną do wskazanego systemu. Gdy usługa obsługująca wysyłkę odnotuje określone zdarzenie, wysyła żądanie HTTP lub HTTPS na wcześniej skonfigurowany adres URL. Odbiorcą może być aplikacja, moduł automatyzacji, system obsługi zgłoszeń albo własny endpoint internetowy. W przeciwieństwie do cyklicznego odpytywania API system docelowy nie musi regularnie pytać dostawcy, czy pojawiły się nowe dane. Otrzymuje komunikat wtedy, gdy zdarzenie rzeczywiście wystąpi.

Do typowych zdarzeń należą przyjęcie wiadomości przez usługę wysyłkową, przekazanie jej do serwera odbiorcy, odrzucenie, odbicie z powodu błędnego adresu, otwarcie wiadomości oraz kliknięcie odnośnika. Dostępny zakres zależy od konkretnego dostawcy poczty i jego konfiguracji. Informacja o otwarciu często jest ustalana na podstawie pobrania niewielkiego obrazu śledzącego, dlatego może być niepełna, gdy klient pocztowy blokuje obrazy lub korzysta z mechanizmu ochrony prywatności. Kliknięcie może natomiast wynikać z przekierowania adresu URL przez system śledzący.

Przebieg dostarczenia zdarzenia do aplikacji

Po wystąpieniu zdarzenia dostawca tworzy żądanie do endpointu webhooka. Najczęściej stosowana jest metoda POST, a dane są przekazywane w formacie JSON. Przykładowy komunikat może zawierać typ zdarzenia, identyfikator wiadomości, czas wystąpienia, adres odbiorcy, temat lub metadane kampanii. Dokładne pola, nazwy zdarzeń i sposób kodowania zależą od usługi, dlatego aplikacja nie powinna zakładać, że każdy webhook e-mail ma taki sam schemat. Przed implementacją należy sprawdzić dokumentację używanego dostawcy.

Endpoint powinien szybko potwierdzić odebranie komunikatu kodem HTTP z zakresu 200–299, a dalsze przetwarzanie może wykonać osobno. Długotrwałe operacje wykonywane bezpośrednio podczas obsługi żądania zwiększają ryzyko przekroczenia limitu czasu i ponownego wysłania tego samego zdarzenia. Dostawcy często ponawiają dostarczenie po błędzie połączenia, przekroczeniu czasu oczekiwania albo otrzymaniu kodu 4xx lub 5xx. Z tego powodu odbiorca musi akceptować możliwość powtórzeń oraz sytuacji, w której zdarzenia dotrą z opóźnieniem lub w innej kolejności.

Walidacja, bezpieczeństwo i odporność na powtórzenia

Adres webhooka powinien korzystać z HTTPS, aby komunikacja była szyfrowana podczas przesyłania. Sama znajomość adresu URL nie zawsze wystarcza do uwierzytelnienia nadawcy. Stosowane są między innymi podpisy kryptograficzne umieszczane w nagłówkach HTTP, tokeny uwierzytelniające oraz ograniczenie dostępu do znanych adresów sieciowych, jeżeli dostawca publikuje odpowiednią listę. Podpis należy sprawdzać na podstawie surowego ciała żądania, przed jego modyfikacją lub ponownym zakodowaniem. Tokenów i kluczy podpisujących nie powinno się umieszczać w publicznym kodzie aplikacji ani w logach.

Obsługa webhooków powinna być idempotentna, czyli wielokrotne przetworzenie tego samego komunikatu nie może powodować wielokrotnego wykonania tej samej operacji. W praktyce aplikacja zapisuje identyfikator zdarzenia lub wiadomości i sprawdza, czy został już obsłużony. Przydatne jest także rejestrowanie czasu odebrania, kodu odpowiedzi, wyniku walidacji oraz przyczyny odrzucenia. Logi nie powinny bez potrzeby zawierać pełnej treści wiadomości, nagłówków autoryzacyjnych ani danych, które nie są potrzebne do diagnozy. W przypadku awarii warto przechowywać komunikat w kolejce lub bezpiecznym magazynie do późniejszego ponowienia, zamiast bezpowrotnie go odrzucać.

Rozpoznawanie problemów z webhookiem e-mail

Brak oczekiwanego powiadomienia nie musi oznaczać awarii samego endpointu. Przyczyną może być wyłączony typ zdarzenia, filtr odbiorców, nieudana wysyłka wiadomości, opóźnienie po stronie dostawcy albo błędny adres URL. Diagnostykę należy rozpocząć od ustalenia, czy zdarzenie zostało zarejestrowane w systemie wysyłkowym. Następnie trzeba sprawdzić historię prób dostarczenia webhooka, kod HTTP zwracany przez endpoint, czas odpowiedzi oraz treść błędu. Kod 404 zwykle wskazuje na nieistniejącą ścieżkę, kod 401 lub 403 na problem z uwierzytelnieniem, a kod 500 na błąd po stronie aplikacji odbierającej.

Warto wykonać test na kontrolnym adresie i porównać otrzymane żądanie z dokumentacją dostawcy. Należy zweryfikować certyfikat TLS, rozwiązywanie nazwy DNS, dostępność portu 443, reguły zapory oraz konfigurację przekierowań HTTP. Jeżeli aplikacja działa na laptopie lub komputerze w sieci lokalnej, publiczny dostawca zwykle nie może połączyć się bezpośrednio z adresem dostępnym wyłącznie wewnątrz tej sieci. W takiej sytuacji potrzebny jest publicznie osiągalny endpoint albo pośrednicząca usługa, a nie samo uruchomienie programu na komputerze użytkownika.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, dlatego może sprawdzić na takim stanowisku między innymi działanie przeglądarki, klienta pocztowego, połączenia sieciowego, certyfikatów oraz lokalnych blokad, które utrudniają korzystanie z aplikacji współpracującej z webhookiem e-mail.