Jak testować powiadomienia o statusie dostarczenia SMS

Czym są powiadomienia o statusie dostarczenia SMS-ów

Powiadomienia o statusie dostarczenia SMS-ów to powiadomienia serwer-serwer, które informują, co się stało po tym, jak SMS opuścił Twój system. Potwierdzenie wysyłki mówi tylko, że wiadomość została zaakceptowana przez dostawcę. Powiadomienie idzie dalej i raportuje stany takie jak w kolejce, wysłane, dostarczone, nieudane lub niedostarczone.

Ta różnica ma znaczenie. Wiadomość może być „wysłana” i nadal nigdy nie dotrzeć do telefonu. Powiadomienie może przyjść kilka sekund później lub może przyjść po opóźnieniu operatora trwającym kilka minut, w zależności od trasy i polityki ponownego wysyłania dostawcy.

Pomyśl o powiadomieniu jako o śladzie potwierdzenia, a nie o samym potwierdzeniu. Odpowiedź API z żądania wysyłki zazwyczaj dowodzi, że dostawca podjął się zadania. Powiadomienie dowodzi, co się wydarzyło następnie, i to jest część, którą musisz przetestować, jeśli Twoja aplikacja zależy od aktualizacji statusu dla powiadomień, potwierdzeń lub procesów wsparcia klienta.

Jeden praktyczny szczegół: powiadomienie jest zazwyczaj wywoływane przez zmianę statusu, a nie przez pierwotne żądanie wysyłki. Jeśli dostawca widzi odpowiedź operatora, raport dostarczenia do telefonu lub błąd z sieci, wysyła żądanie HTTP do Twojego punktu końcowego. Jeśli wiadomość nigdy nie opuści kolejki dostawcy, możesz zobaczyć tylko wczesne stany.

Wymagania wstępne do testowania powiadomień

Potrzebujesz czterech rzeczy, zanim będziesz mógł przetestować powiadomienia o statusie dostarczenia SMS-ów: konto dostawcy SMS, adres URL powiadomienia, dostęp do logów serwera i numer testowy. Najlepiej, jeśli to telefon, którym zarządzasz. To sprawia, że test jest powtarzalny i unika zgadywania dotyczącego zachowania operatora.

Miej gotowy publiczny punkt końcowy HTTPS, nawet jeśli na razie tylko loguje żądania. Wielu dostawców odmawia dostarczania powiadomień przez zwykłe HTTP, a niektóre środowiska testowe blokują prywatne adresy. Potrzebujesz również sposobu na inspekcję nagłówków żądań, treści ciała i kodów odpowiedzi z Twojego serwera.

Trzymaj otwarty pulpit nawigacyjny dostawcy. Będziesz porównywać identyfikatory wiadomości, znaczniki czasowe i zdarzenia statusu tam. Jeśli Twój dostawca oferuje powtórne odtwarzanie webhooków lub historię zdarzeń, włącz to przed rozpoczęciem. To oszczędza czas później, gdy powiadomienie przychodzi dwa razy lub wcale.

Jeśli Twój przepływ SMS-ów jest częścią większego systemu wiadomości, warto również przejrzeć powiązane obsługi zdarzeń, takie jak zdarzenia webhooków e-mail dla wiadomości transakcyjnych. Mechanika jest podobna w jednym ważnym aspekcie: Twój serwer musi szybko akceptować i weryfikować ładunki zdarzeń, a następnie je przechowywać, zanim nastąpi ponowne wysłanie.

Krok 1: Skonfiguruj punkt końcowy testowego wywołania zwrotnego

Utwórz dedykowany punkt końcowy dla wywołań zwrotnych, na przykład /sms-status, zamiast wysyłać je do ogólnej trasy API. Mały, specjalnie zaprojektowany punkt końcowy ułatwia testowanie, ponieważ każde żądanie należy do jednego zadania. Możesz rejestrować surowe dane, nagłówki, czas odpowiedzi i wszelkie błędy parsowania w jednym miejscu.

Uczyń punkt końcowy publicznym i HTTPS. Użyj certyfikatu, któremu ufa twój dostawca. Jeśli dostawca nie może dotrzeć do URL, wywołanie zwrotne nie powiedzie się, zanim twój kod nawet się uruchomi. To brzmi oczywiście, ale to pierwsze miejsce, w którym wiele testów się psuje.

Zwróć szybką odpowiedź 200 po zapisaniu ładunku. Nie czekaj na raport z bazy danych ani na wywołanie usługi downstream. Punkt końcowy wywołania zwrotnego powinien najpierw potwierdzić odbiór, a następnie wykonać dodatkową pracę. Wolna odpowiedź może wywołać ponowne próby, a ponowne próby sprawiają, że wyniki testów są chaotyczne.

Dla szybkiej konfiguracji możesz zapisać surowe żądanie do pliku dziennika i wydrukować ciało na konsoli. To wystarczy na pierwszy test. Później możesz przechowywać wiersze w tabeli z polami takimi jak provider, message_id, status, received_at i signature_header.

Krok 2: Wyślij testowy SMS z włączonym śledzeniem wywołań zwrotnych

Użyj API dostawcy lub panelu, aby wysłać wiadomość testową i ustawić adres URL zwrotny w żądaniu wiadomości lub ustawieniach konta. Niektórzy dostawcy nazywają to zwrotem statusu, adresem URL potwierdzenia dostawy lub punktem końcowym webhooka. Etykieta się zmienia; funkcja pozostaje ta sama.

Upewnij się, że śledzenie zwrotów jest włączone dla konkretnej wiadomości. Żądanie wysłania może zakończyć się sukcesem, nawet jeśli dostarczanie zdarzeń nie jest aktywne. Jeśli twój dostawca obsługuje flagi dla poszczególnych wiadomości, ustaw je wyraźnie, aby nie polegać na domyślnych ustawieniach, które mogą się różnić w zależności od konta lub środowiska.

Użyj własnego numeru testowego. Najpierw wyślij krótką wiadomość, na przykład sześciowyrazowy alert. Krótkie teksty są łatwiejsze do zauważenia na telefonie i łatwiejsze do porównania z logami dostawcy. Jeden dodatkowy znak może mieć znaczenie, jeśli testujesz konkatenację lub kodowanie, więc trzymaj pierwszy test prosty.

Jeśli twoja aplikacja już obsługuje inne zdarzenia webhook, ta sama zasada ma zastosowanie. Zespoły, które już korzystają z narzędzi do testowania dostarczalności e-maili · YourTrend, często uznają testy SMS za prostsze, ponieważ ta sama nawyk pomaga: zarejestruj dokładne żądanie, a następnie porównaj je z stroną dostawcy, zamiast polegać na pamięci.

Krok 3: Wyzwól typowe stany dostarczania

Testuj więcej niż jeden stan. Pojedyncza dostarczona wiadomość niewiele dowodzi. Chcesz zobaczyć stany w kolejce, wysłane, dostarczone, nieudane i niedostarczone, aby wiedzieć, że ścieżka zwrotna działa w normalnych i niekorzystnych warunkach.

Najłatwiejszym stanem do wyzwolenia jest zazwyczaj stan w kolejce. Wyślij testowy SMS i obserwuj zwrot dla początkowego statusu. Dostawca może najpierw oznaczyć wiadomość jako zaakceptowaną, a następnie zaktualizować ją, gdy opuści kolejkę. Jeśli uchwycisz tylko pierwsze zdarzenie, twoja logika może przegapić późniejszą zmianę.

Aby wyzwolić stan nieudany lub niedostarczony, użyj numeru, który jest nieprawidłowy, nieaktywny lub niedostępny w sieci operatora, w zależności od zasad testowych twojego dostawcy. Niektórzy dostawcy oferują również numery sandboxowe lub kody symulacyjne, które wymuszają konkretne stany. Są one przydatne, ponieważ zmniejszają niepewność.

Dostarczony to stan, na którym najbardziej zależy ludziom, ale to także ten, którego nie powinieneś zakładać. Telefon musi być dostępny, sieć musi zwrócić potwierdzenie dostawy, a dostawca musi przemapować to potwierdzenie na zwrot. Trzy ruchome części. Jedno pominięte skok wystarczy.

Wysłany nie jest tym samym co dostarczony. Status wysłania często oznacza, że dostawca przekazał wiadomość operatorowi lub przynajmniej podjął próbę dostarczenia. Jeśli twój proces biznesowy zaczyna odliczanie od „wysłane”, możesz obiecywać użytkownikom coś, co jeszcze się nie wydarzyło.

Krok 4: Zweryfikuj ładunek zwrotny

Otwórz ciało żądania i sprawdź każde pole, które obiecuje dostawca. Identyfikatory wiadomości powinny odpowiadać oryginalnej odpowiedzi na wysyłkę. Znaczniki czasowe powinny mieć sens w strefie czasowej Twojego konta lub UTC, w zależności od tego, jak dostawca je formatuje. Wartości statusu powinny mieścić się w zestawie udokumentowanym przez dostawcę.

Sprawdź dane nadawcy i odbiorcy. Wiadomość testowa wysłana z jednego numeru powinna wrócić z tym samym numerem docelowym w odpowiedzi, chyba że dostawca go zamaskuje lub znormalizuje. Jeśli ładunek zawiera kody przewoźników, powody błędów lub kierunek wiadomości, również je przechowuj. Staną się przydatne później, gdy klient powie: „Nigdy tego nie otrzymałem.”

Nagłówki podpisu zasługują na prawdziwą uwagę. Wielu dostawców podpisuje odpowiedzi, aby Twój serwer mógł potwierdzić, że żądanie naprawdę pochodzi od nich. Sprawdź dokładną nazwę nagłówka, algorytm podpisu oraz wspólny sekret lub przepływ klucza publicznego. Jeśli pominiesz weryfikację podczas testowania, nie testujesz tej samej ścieżki, której użyjesz w produkcji.

Użyj jednego przejścia weryfikacyjnego dla struktury i jednego dla autentyczności. Najpierw potwierdź, że JSON lub ciało formularza jest poprawnie analizowane. Następnie potwierdź, że podpis lub token odpowiada temu, czego oczekuje Twój dostawca. Ta dwuetapowa kontrola wychwytuje zarówno źle sformatowane ładunki, jak i fałszywe żądania.

Krok 5: Porównaj dzienniki dostawcy z dziennikami swojego webhooka

Teraz dopasuj historię zdarzeń dostawcy do żądań, które otrzymał twój serwer. Użyj najpierw identyfikatora wiadomości. Następnie porównaj status, znacznik czasu i liczbę prób. Jeśli jedna strona pokazuje trzy zdarzenia, a druga dwa, masz lukę, którą warto naprawić, zanim ktoś uzna to za problem produkcyjny.

Pulpity nawigacyjne dostawcy czasami grupują zdarzenia według wiadomości, a czasami według żądania. Twoje własne dzienniki powinny być dokładniejsze. Zapisz metodę HTTP, kod statusu zwrócony przez twój serwer, treść żądania i czas przybycia do sekundy, jeśli to możliwe. To daje ci czyste porównanie linia po linii.

Jeśli twój dostawca oferuje eksportowane dzienniki, pobierz je w tym samym oknie testowym. Dziesięciominutowe opóźnienie między wysyłkami może ułatwić porównanie dzienników. Chodzi nie tylko o to, aby zobaczyć, że callback dotarł, ale aby udowodnić, że twój serwer i dostawca zgadzają się co do tego, które zdarzenie miało miejsce i kiedy.

Dla zespołów, które już porównują zdarzenia mailowe, to wydaje się znajome. Ta sama zasada stosowana w najlepszych praktykach obsługi zwrotów e-mail ma tu zastosowanie: nie ufaj tylko szczęśliwej ścieżce. Porównaj rekord dostawcy, swój rekord przyjęcia i końcowy stan, który przechowywała twoja aplikacja.

Krok 6: Rozwiązywanie problemów z brakującymi lub niepoprawnymi callbackami

Jeśli callback nigdy nie dociera, zacznij od adresu URL punktu końcowego. Sprawdź pisownię, protokół, port i ścieżkę. Jeden zbłąkany znak może wysłać żądanie donikąd. Następnie potwierdź, że punkt końcowy jest osiągalny z publicznego internetu, a nie tylko z sieci biurowej.

Czas oczekiwania to następna kwestia. Jeśli twój serwer zbyt długo odpowiada, dostawca może spróbować ponownie lub oznaczyć callback jako nieudany. Utrzymuj handler krótki. Najpierw zapisz ładunek, zwróć 200, a resztę przetwórz później.

Reguły zapory mogą zablokować żądanie, zanim twój kod je zobaczy. Tak samo mogą działać listy dozwolonych adresów IP, reguły WAF lub podstawowa autoryzacja, której dostawca nie może zrealizować. Jeśli twój punkt końcowy wymaga autoryzacji, upewnij się, że dostawca obsługuje dokładnie tę metodę, którą wybrałeś. Niektóre systemy obsługują sekret w ciągu zapytania, inne wysyłają nagłówek autoryzacji, a niektóre robią to i to.

Źle sformatowany JSON zazwyczaj oznacza, że dostawca użył innego typu treści, niż się spodziewałeś, lub twój parser odrzucił kształt pola, którego nie testowałeś. Sprawdź surowe ciało. Nie ufaj tylko wersji sformatowanej. Brak przecinka w twoim własnym kodzie również może sprawić, że będzie wyglądać, jakby dostawca coś zepsuł.

Duplikaty zdarzeń zdarzają się częściej, niż zespoły się spodziewają. Dostawca może ponowić próbę po upływie czasu, nawet jeśli pierwsze wywołanie zwrotne ostatecznie się zakończyło. Twój handler powinien akceptować ten sam identyfikator wiadomości i status więcej niż raz, nie tworząc duplikatów wierszy ani duplikatów alertów. Przechowuj zasady idempotencji w notatkach testowych.

Jeśli podpisy nie pasują, porównaj dokładne bajty, które zostały wysłane, z bajtami użytymi przez twój weryfikator. Kodowanie znaków, łamanie linii i parsowanie ciała mogą zmienić wynik. To jeden z powodów, dla których testowanie statusu dostarczania SMS-ów wymaga kroku z surowym żądaniem, a nie tylko kroku z obiektem sparsowanym.

Krok 7: Potwierdzenie gotowości do produkcji

Powtórz pełny test w środowisku staging lub w konfiguracji podobnej do produkcyjnej z prawdziwym HTTPS, tą samą ścieżką kodu i tym samym miejscem logowania. Użyj konta dostawcy na żywo, jeśli twoje konto testowe zachowuje się inaczej. Fałszywe środowisko może ukrywać problemy z certyfikatami, problemy z DNS lub limity, które pojawiają się dopiero po wdrożeniu.

Dokumentuj oczekiwane zachowanie callbacków w jednym miejscu. Zapisz, jakie statusy oczekujesz, które z nich wywołują powiadomienia dla użytkowników, a które powinny tylko aktualizować wewnętrzne logi. Jeśli dostawca wysyła ponowne próby po 30 sekundach, również to zapisz. Przyszłe debugowanie staje się szybsze, gdy zespół zna oczekiwane opóźnienie.

Ustaw regułę monitorowania dla brakujących callbacków. Jednym prostym sprawdzeniem jest oznaczenie wiadomości, które pozostają w statusie wysłanym dłużej niż twój normalny czas. Innym jest powiadomienie, gdy punkt końcowy callbacka zwraca cokolwiek innego niż 200 przez więcej niż 3 żądania z rzędu.

Jeśli śledzenie statusu SMS jest częścią szerszego systemu wiadomości, utrzymuj ten sam standard jakości w różnych kanałach. Zespoły często łączą testy SMS z DKIM SPF DMARC dla transakcyjnych wiadomości e-mail, ponieważ oba systemy zależą od kontroli tożsamości, dostarczania zdarzeń i jasnego zarządzania błędami. Jedna strona zawodzi cicho. Druga zawodzi głośno. Obie zasługują na testy.

Na koniec, zapisz jeden znany dobry przykład callbacka w swoich wewnętrznych dokumentach. Dołącz ciało żądania, nagłówek podpisu, kod odpowiedzi i stronę zdarzeń dostawcy. Ten pojedynczy przykład stanie się twoim odniesieniem, gdy przyszłe wydanie zmieni kształt ładunku lub gdy operator zacznie zachowywać się inaczej.