Webhooki i statusy doręczeń: monitoring wysyłek SMS od strony technicznej
Dodał: Marta Data: 2026-11-01 08:26:01 (czytane: 2009)
Cykl życia wiadomości SMS
Każdy SMS przechodzi przez kilka etapów. Najpierw aplikacja wysyła żądanie do API bramki. Bramka waliduje je, nadaje wiadomości identyfikator i przekazuje ją do operatora sieci komórkowej. Operator próbuje dostarczyć SMS do urządzenia, a następnie odsyła raport doręczenia, tzw. DLR (Delivery Report). Dopiero ten raport mówi, co faktycznie stało się z wiadomością.
Najważniejsze statusy doręczeń
Nazewnictwo różni się w zależności od dostawcy, ale logika jest podobna. Typowe statusy to:
-
przyjęta lub w kolejce ? bramka zaakceptowała wiadomość i czeka na jej wysłanie,
-
wysłana ? wiadomość trafiła do operatora,
-
doręczona ? operator potwierdził dostarczenie do telefonu,
-
niedoręczona ? próba się nie powiodła, np. z powodu nieaktywnego numeru,
-
wygasła ? telefon był wyłączony lub poza zasięgiem dłużej niż okres ważności wiadomości,
-
odrzucona ? wiadomość zablokowano, np. z powodu błędnego numeru lub braku środków.
Status ?doręczona? potwierdzony przez operatora to najpewniejsza informacja, jaką można uzyskać w kanale SMS.
Polling czy webhooki
Statusy można pobierać na dwa sposoby.
Odpytywanie API (polling)
Aplikacja co jakiś czas pyta bramkę o status wiadomości po jej identyfikatorze. Rozwiązanie jest proste, ale nieefektywne. Przy dużym wolumenie generuje tysiące zbędnych zapytań, a informacja i tak dociera z opóźnieniem zależnym od częstotliwości odpytywania.
Webhooki (callback URL)
W tym modelu to bramka wysyła informację do aplikacji, gdy tylko status się zmieni. Wystarczy wskazać adres URL, pod który mają trafiać powiadomienia. Bramka wykonuje na niego żądanie HTTP z danymi: identyfikatorem wiadomości, numerem, nowym statusem i znacznikiem czasu. To podejście jest szybsze, tańsze i lepiej się skaluje.
Jak poprawnie zaimplementować endpoint webhooka?
Odbiór webhooków wydaje się prosty, ale kilka szczegółów decyduje o niezawodności.
Szybka odpowiedź
Endpoint powinien jak najszybciej zwrócić kod HTTP 200, a właściwe przetwarzanie danych przekazać do kolejki. Jeśli odpowiedź się opóźni, bramka może uznać próbę za nieudaną i ponowić wysyłkę.
Idempotentność
Ten sam status może dotrzeć więcej niż raz. Obsługa powinna rozpoznawać duplikaty po identyfikatorze wiadomości i statusie, tak aby powtórzone powiadomienie nie wywołało podwójnej akcji.
Kolejność zdarzeń
Statusy nie zawsze przychodzą w porządku chronologicznym. Warto zapisywać znacznik czasu i nie nadpisywać statusu końcowego, np. ?doręczona?, statusem pośrednim, który dotarł później.
Bezpieczeństwo
Endpoint jest publiczny, więc należy weryfikować źródło żądań, np. przez token w adresie, podpis wiadomości lub listę dozwolonych adresów IP. Komunikacja powinna odbywać się wyłącznie przez HTTPS.
Co zrobić z danymi o statusach
Zebrane statusy to cenne źródło wiedzy. Pozwalają automatycznie oczyszczać bazę z nieaktywnych numerów, uruchamiać kanał zapasowy, np. e-mail, gdy SMS z kodem jednorazowym nie dotrze, oraz mierzyć realną doręczalność kampanii. Monitoring odsetka wiadomości niedoręczonych pomaga też szybko wykryć problem, zanim zauważą go klienci.
Wybór API z myślą o monitoringu
Przy wyborze dostawcy warto sprawdzić, czy SMS API udostępnia szczegółowe statusy potwierdzane przez operatorów, obsługuje callbacki i ma czytelną dokumentację. Istotne jest także wsparcie techniczne na etapie integracji ? oszczędza godziny debugowania.
Podsumowanie
Statusy doręczeń zamieniają wysyłkę SMS z działania ?na ślepo? w mierzalny proces. Webhooki pozwalają reagować na nie w czasie rzeczywistym, pod warunkiem że endpoint jest szybki, idempotentny i zabezpieczony. To niewielki nakład pracy, który daje pełną kontrolę nad komunikacją.
/Artykuł sponsorowany/




































