Webhooki e-mail: jak synchronizować odbicia i wypisy z CRM

Webhooki e-mail wysyłają zdarzenia odbić i wypisów na endpoint, który sam kontrolujesz. Dzięki temu CRM może zaktualizować kontakt i przestać do niego pisać w chwili, gdy zdarzenie nastąpi. A bez nich? CRM dalej wysyła wiadomości do osób, których adresy już się odbiły albo które wypisały się w platformie mailingowej. To szkodzi reputacji nadawcy i lekceważy zgodę, którą kontakt już wycofał. Poniżej: których zdarzeń używać, jak zbudować endpoint, jak mapować zdarzenia na pola w CRM, jak radzić sobie z ponowieniami i duplikatami oraz jak przetestować synchronizację, zanim zbliży się do danych produkcyjnych.

Co wysyłają webhooki e-mail i które zdarzenia mają znaczenie dla CRM

Webhook to żądanie HTTP POST, które platforma mailingowa wysyła na Twój adres URL za każdym razem, gdy coś się wydarzy. Bez odpytywania API o zmiany. MailCraft wysyła powiadomienia o czterech rodzajach zdarzeń: otwarciach, kliknięciach, odbiciach i wypisach. Zarówno webhooki, jak i REST API i webhooki są dostępne w planie Pro. Dla porządku w CRM liczą się odbicia i wypisy, bo zmieniają to, do kogo wolno Ci wysyłać. Otwarcia i kliknięcia? To sygnały zaangażowania. Miło je mieć, nic więcej.

• Odbicia: zaktualizuj status adresu e-mail, a przy trwałych błędach zablokuj dalsze wysyłki.
• Wypisy: ustaw flagę rezygnacji z marketingu i zapisz, kiedy i gdzie to nastąpiło.
• Otwarcia: dodaj aktywność na osi czasu kontaktu albo uwzględnij ją w scoringu leadów.
• Kliknięcia: zapisz, który link kliknął kontakt, na potrzeby scoringu albo kontaktu ze strony handlowców.

Jak skonfigurować endpoint webhooka dla odbić

Potrzebujesz jednego endpointu HTTPS, który przyjmie żądanie POST, zweryfikuje je, zapisze surowy payload i szybko odpowie kodem 2xx. Z mojego doświadczenia taka kolejność dobrze się sprawdza:

1. Umieść endpoint pod stałym, publicznie dostępnym adresem HTTPS.
2. Zarejestruj ten adres w platformie mailingowej i wybierz zdarzenia, które chcesz otrzymywać.
3. Zapisz surową treść żądania, zanim cokolwiek sparsujesz albo przekształcisz.
4. Odpowiedz kodem 200, gdy tylko payload zostanie zapisany.
5. Aktualizacje w CRM wykonuj w zadaniu w tle, które czyta dane z tego zapisu.

Skąd ten pośpiech z potwierdzeniem? Wolne handlery przekraczają limit czasu, a wtedy platforma ponownie wysyła zdarzenia, które być może już przetworzyłeś. W efekcie wykonujesz tę samą pracę dwa razy (albo, co gorsza, w złej kolejności). Jeśli nie łączyłeś się jeszcze z platformą programowo, zacznij od tego, jak wysłać pierwsze zapytanie do API. Najpierw oswój się z uwierzytelnianiem i formatem danych, dopiero potem podłączaj webhooki.

Twarde i miękkie odbicia: co CRM ma zrobić z każdym z nich?

Twarde odbicie to trwały błąd doręczenia i kontakt powinien zostać oznaczony jako niedostępny. Miękkie odbicie jest tymczasowe. Policz je i na tym koniec. Z którym masz do czynienia, powie Ci pierwsza cyfra rozszerzonego kodu statusu: standard rozszerzonych kodów statusu używa 5.x.x dla błędów trwałych i 4.x.x dla przejściowych. Każde odbicie zmapuj na te pola w CRM:

• Status adresu e-mail: poprawny, z miękkimi odbiciami albo niedostępny.
• Typ odbicia: twarde albo miękkie, odczytane z kodu statusu.
• Data ostatniego odbicia: znacznik czasu zdarzenia, a nie moment, w którym je przetworzyłeś.
• Flaga zakazu wysyłki: tylko przy twardych odbiciach.

Nie oznaczaj kontaktu po jednym miękkim odbiciu. Pełne skrzynki i przeciążone serwery zwykle same wracają do normy. Blokuj adres dopiero po powtarzających się błędach. Gdzie dokładnie postawić granicę, decydujesz sam, a zasady odczytywania raportu odbić pomogą Ci wybrać rozsądny próg.

Synchronizacja wypisów z CRM bez utraty historii zgód

Zdarzenie wypisu ustawia flagę rezygnacji z marketingu na pasującym kontakcie w CRM. Nigdy nie usuwa rekordu. Nigdy. Dopasowuj kontakty po znormalizowanym adresie e-mail, czyli zapisanym małymi literami i bez białych znaków na początku i końcu. Z góry ustal też, co się dzieje, gdy kilka rekordów w CRM ma ten sam adres. Zwykle wszystkie dostają flagę, bo to osoba zrezygnowała, a nie jeden konkretny rekord. Zapisuj znacznik czasu i źródło każdej rezygnacji, żeby w razie pytań móc później udowodnić historię zgód. Następnie połącz rezygnacje i twarde odbicia w jedną listę, którą CRM sprawdza przed każdą wysyłką. Poradnik o prowadzeniu listy wykluczeń pokazuje, jak ją zbudować.

Obsługa ponowień i duplikatów webhooków dzięki idempotencji

Webhooki są doręczane co najmniej raz. Dlatego handler musi dojść do tego samego stanu niezależnie od tego, czy zdarzenie przyjdzie raz, czy trzy razy. To właśnie idempotencja. W praktyce: zapisuj unikalny klucz każdego zdarzenia i pomijaj klucze, które już widziałeś. Jeśli payload zawiera ID zdarzenia, użyj go. Jeśli nie, zbuduj klucz z adresu e-mail, typu zdarzenia i znacznika czasu. Ta sama dyscyplina w nadawaniu kluczy przydaje się po stronie analityki, gdzie spójne parametry UTM w mailingach chronią raporty przed zdublowanymi i rozjechanymi źródłami ruchu.

Drugą pułapką jest kolejność. Zdarzenia mogą przychodzić w innej kolejności, niż wystąpiły, więc porównuj znaczniki czasu i nigdy nie pozwól, by starsze zdarzenie nadpisało nowszy stan. Spóźnione odbicie nie powinno na przykład cofać ponownego potwierdzenia zgody, które nastąpiło po nim. Zwracaj status inny niż 2xx tylko wtedy, gdy naprawdę chcesz, żeby platforma ponowiła wysyłkę. Loguj każdy błąd i ustaw alert na sytuację, gdy ten sam błąd ciągle wraca.

Jak testować i monitorować synchronizację

Testuj na prawdziwych zdarzeniach z osobnej listy testowej, zanim webhook w ogóle dotknie produkcyjnych danych w CRM. Przejdź przez tę listę kontrolną:

• Wyślij wiadomość na adres, o którym wiesz, że jest nieprawidłowy, i sprawdź, czy twarde odbicie trafia do CRM.
• Wypisz kontakt testowy i sprawdź, czy flaga rezygnacji, znacznik czasu i źródło są ustawione.
• Wyślij ten sam payload dwa razy i sprawdź, czy pola w CRM zmieniają się tylko raz.

Po uruchomieniu codziennie porównuj zdarzenia odebrane z przetworzonymi i ustaw alert na każdy błąd zwracany przez endpoint. Regularnie uzgadniaj też CRM z danymi o wykluczeniach z platformy. Same ponowienia nie odzyskają tego, co przepadło podczas awarii. Uzgadnianie danych tak.

Jeśli chcesz jednego praktycznego pierwszego kroku: subskrybuj tylko odbicia i wypisy, zadbaj o idempotencję handlera, a otwarcia i kliknięcia dodaj, gdy wykluczenia już działają. Zbudowane w tej kolejności webhooki e-mail utrzymują CRM w zgodzie z platformą mailingową i nikt nie dostaje wiadomości, których odmówił albo których nie może odebrać.

FAQ