Як тестувати callbacks статусу доставки SMS

Що таке callbacks статусу доставки SMS

Callbacks статусу доставки SMS — це серверні сповіщення, що повідомляють, що сталося після того, як SMS залишило вашу систему. Підтвердження відправлення лише каже, що повідомлення було прийняте провайдером. Callback йде далі й повідомляє про такі стани, як у черзі, надіслано, доставлено, помилка або недоставлено.

Ця різниця має значення. Повідомлення може бути “надіслано”, але так і не дійти до телефону. Callback може прийти за кілька секунд, а може — після затримки з боку оператора, що триває кілька хвилин, залежно від маршруту та політики повторних спроб провайдера.

Сприймайте callback як слід квитанцій, а не саму квитанцію. Відповідь API на запит відправлення зазвичай доводить, що провайдер узяв задачу в роботу. Callback доводить, що сталося далі, і саме це вам потрібно тестувати, якщо ваша програма залежить від оновлень статусу для сповіщень, квитанцій або процесів підтримки клієнтів.

Одна практична деталь: callback зазвичай запускається зміною статусу, а не початковим запитом на відправлення. Якщо провайдер отримує відповідь від оператора, звіт про доставку на телефон чи помилку від мережі, він надсилає HTTP-запит на ваш endpoint. Якщо повідомлення так і не виходить за межі черги провайдера, ви можете побачити лише ранні стани.

Що потрібно перед тестуванням callbacks

Щоб протестувати callbacks статусу доставки SMS, вам потрібні чотири речі: акаунт у SMS-провайдера, callback URL, доступ до серверних логів і тестовий номер. Найкраще використовувати телефон, яким ви керуєте самі. Це робить тест повторюваним і позбавляє необхідності вгадувати поведінку оператора.

Підготуйте публічний HTTPS endpoint, навіть якщо зараз він лише записує запити в лог. Багато провайдерів не приймають звичайний HTTP для доставки callbacks, а деякі тестові середовища блокують приватні адреси. Також вам потрібен спосіб переглядати заголовки запиту, вміст тіла та коди відповіді з вашого сервера.

Тримайте панель провайдера відкритою. Там ви порівнюватимете ID повідомлень, часові мітки та події статусу. Якщо провайдер підтримує повторне відтворення webhook або історію подій, увімкніть це до початку. Це заощадить час, якщо callback прийде двічі або не прийде взагалі.

Якщо ваш SMS-процес є частиною ширшої системи обміну повідомленнями, корисно також переглянути пов’язані події, наприклад події email webhook для транзакційних листів. Механіка тут схожа в одному важливому аспекті: ваш сервер має швидко приймати та перевіряти payload події, а потім зберігати його до того, як спрацює повторна спроба.

Крок 1: Налаштуйте тестовий endpoint для callback

Створіть окремий endpoint для callbacks, наприклад /sms-status, замість того, щоб надсилати їх у загальний API-route. Невеликий, спеціально призначений endpoint спрощує тестування, бо кожен запит належить одній задачі. Ви можете вести журнал сирого тіла запиту, заголовків, часу відповіді та будь-яких помилок парсингу в одному місці.

Зробіть endpoint публічним і HTTPS. Використовуйте сертифікат, якому довіряє ваш провайдер. Якщо провайдер не може дістатися до URL, callback не спрацює ще до того, як запуститься ваш код. Звучить очевидно, але саме тут ламається багато тестів.

Поверніть швидку відповідь 200 після збереження payload. Не чекайте звіту з бази даних або виклику стороннього сервісу. Endpoint callback має спочатку підтвердити отримання, а всі додаткові дії виконувати потім. Повільна відповідь може спровокувати повторні спроби, а повторні спроби ускладнюють результати тесту.

Для швидкого старту можна записувати сирий запит у файл логів і виводити body в консоль. Для першого тесту цього достатньо. Пізніше можна зберігати рядки в таблицю з полями на кшталт provider, message_id, status, received_at і signature_header.

Крок 2: Надішліть тестове SMS з увімкненим відстеженням callback

Скористайтеся API або панеллю провайдера, щоб надіслати тестове повідомлення, і вкажіть callback URL у запиті повідомлення або в налаштуваннях акаунта. Деякі провайдери називають це статусним callback, URL для delivery receipt або webhook endpoint. Назва змінюється; функція — ні.

Переконайтеся, що відстеження callback увімкнене саме для цього повідомлення. Запит на відправлення може успішно виконатися, навіть якщо доставка подій не активована. Якщо провайдер підтримує прапорці на рівні окремого повідомлення, задайте їх явно, щоб не покладатися на значення за замовчуванням, яке може відрізнятися залежно від акаунта чи середовища.

Використовуйте свій тестовий номер. Спочатку надішліть коротке повідомлення, наприклад сповіщення з шести слів. Короткий текст легше помітити на телефоні й простіше порівнювати з логами провайдера. Одна зайва літера може мати значення, якщо ви тестуєте об’єднання повідомлень або кодування, тож для першого тесту краще залишити текст простим.

Якщо ваш стек уже обробляє інші webhook-події, діє та сама дисципліна. Команди, які вже використовують інструменти тестування deliverability email · YourTrend, часто знаходять SMS-тести простішими, бо допомагає та сама звичка: записати точний запит, а потім порівняти його з даними у вендора, а не покладатися на пам’ять.

Крок 3: Запустіть типові стани доставки

Тестуйте більше ніж один стан. Одне доставлене повідомлення майже нічого не доводить. Вам потрібно побачити стани queued, sent, delivered, failed і undelivered, щоб знати, що шлях callback працює як у нормальних, так і в проблемних умовах.

Найпростіше зазвичай отримати стан queued. Надішліть тестове SMS і стежте за callback початкового статусу. Спочатку провайдер може позначити повідомлення як прийняте, а потім оновити його, коли воно вийде з черги. Якщо ви захоплюєте лише першу подію, ваша логіка може пропустити подальший перехід.

Щоб викликати failed або undelivered, використайте номер, який є недійсним, неактивним або недоступним у мережі оператора, залежно від тестових правил вашого провайдера. Деякі провайдери також надають sandbox-номери або коди симуляції, що примусово задають певні стани. Це зручно, бо зменшує невизначеність.

Delivered — це стан, який найбільше цікавить людей, але саме його не варто вважати автоматичним. Телефон має бути доступним, мережа має повернути звіт про доставку, а провайдер має перетворити цей звіт на callback. Три рухомі частини. Достатньо втратити один етап.

Sent — це не те саме, що delivered. Статус sent часто означає, що провайдер передав повідомлення оператору або принаймні спробував доставку. Якщо ваш бізнес-процес починає відлік від “sent”, ви можете обіцяти користувачам те, що ще не сталося.

Крок 4: Перевірте payload callback

Відкрийте body запиту та перевірте кожне поле, яке обіцяє провайдер. ID повідомлення мають збігатися з початковою відповіддю на відправлення. Часові мітки повинні мати сенс у часовому поясі вашого акаунта або в UTC — залежно від того, як їх форматує провайдер. Значення статусів мають залишатися в межах набору, описаного провайдером.

Подивіться на дані відправника та одержувача. Тестове повідомлення, надіслане з одного номера, має повернутися в callback із тим самим номером призначення, якщо провайдер не маскує та не нормалізує його. Якщо payload містить коди оператора, причини помилок або напрямок повідомлення, зберігайте й це. Пізніше це стане корисним, коли клієнт скаже: “Я його не отримав”.

Заголовкам підпису варто приділити особливу увагу. Багато провайдерів підписують callbacks, щоб ваш сервер міг переконатися, що запит справді надійшов від них. Перевірте точну назву заголовка, алгоритм підпису та схему з shared secret або public key. Якщо ви пропустите перевірку під час тестування, ви не тестуєте той самий шлях, який використовуватимете в продакшені.

Використайте один прохід для перевірки структури і ще один — для автентичності. Спочатку переконайтеся, що JSON або form body коректно парситься. Потім перевірте, що підпис або токен відповідає тому, чого очікує провайдер. Така двоетапна перевірка ловить і некоректні payload, і підроблені запити.

Крок 5: Порівняйте логи провайдера зі своїми webhook-логами

Тепер зіставте історію подій провайдера з запитами, які отримав ваш сервер. Почніть з message ID. Потім порівняйте статус, часову мітку та кількість повторних спроб. Якщо з одного боку видно три події, а з іншого — дві, у вас є розрив, який варто виправити ще до того, як хтось назве це проблемою в продакшені.

Панелі провайдерів іноді групують події за повідомленням, а іноді — за запитом. Ваші власні логи мають бути точнішими. Записуйте HTTP-метод, код відповіді, який повернув ваш сервер, body запиту та час надходження до секунди, якщо це можливо. Це дає чітке порівняння рядок за рядком.

Якщо провайдер пропонує експорт логів, витягніть їх у той самий тестовий проміжок. Затримка в десять хвилин між відправленнями може полегшити порівняння логів. Мета не просто побачити, що callback прийшов, а довести, що ваш сервер і провайдер погоджуються, яка саме подія сталася і коли.

Для команд, які вже порівнюють поштові події, це здається знайомим. Та сама звичка, яку використовують для кращих практик обробки email bounce, працює і тут: не довіряйте лише щасливому шляху. Порівняйте запис у вендора, свій запис прийому та фінальний стан, який зберегла ваша програма.

Крок 6: Усуньте проблеми з відсутніми або неправильними callback

Якщо callback так і не приходить, почніть з URL endpoint. Перевірте написання, протокол, порт і шлях. Одна зайва або відсутня літера може спрямувати запит у нікуди. Потім переконайтеся, що endpoint доступний з публічного інтернету, а не лише з офісної мережі.

Далі — таймаути. Якщо ваш сервер занадто довго відповідає, провайдер може повторити спробу або позначити callback як невдалий. Тримайте обробник коротким. Спочатку збережіть payload, поверніть 200, а решту обробляйте пізніше.

Правила firewall можуть заблокувати запит ще до того, як його побачить ваш код. Так само можуть завадити IP allowlist, правила WAF або basic auth, який провайдер не може пройти. Якщо ваш endpoint потребує автентифікації, переконайтеся, що провайдер підтримує саме той метод, який ви вибрали. Деякі системи підтримують secret у query string, інші надсилають заголовок Authorization, а деякі роблять і те, і те.

Некоректний JSON зазвичай означає, що провайдер використав інший content type, ніж ви очікували, або ваш парсер відхилив форму поля, яку ви не тестували. Перевірте сирий body. Не покладайтеся лише на красиво відформатовану версію. Відсутня кома у вашому власному коді теж може створити враження, ніби зламався провайдер.

Дублікати подій трапляються частіше, ніж команди очікують. Провайдер може повторити запит після таймауту, навіть якщо перший callback зрештою був успішним. Ваш обробник має приймати один і той самий message ID та статус більше одного разу, не створюючи дублікати рядків або дублікати сповіщень. Запишіть правила ідемпотентності в нотатки до тесту.

Якщо підписи не проходять перевірку, порівняйте точні байти, які були надіслані, з байтами, які використав ваш verifier. Кодування символів, переноси рядків і парсинг body можуть змінити результат. Саме тому як тестувати callbacks статусу доставки SMS потребує кроку з сирим запитом, а не лише кроку з уже розпарсеним об’єктом.

Крок 7: Переконайтеся в готовності до продакшена

Повторіть повний тест у staging або в середовищі, схожому на продакшен, із реальним HTTPS, тим самим шляхом коду та тим самим місцем зберігання логів. Використайте живий акаунт провайдера, якщо тестовий поводиться інакше. Фейкове середовище може приховати проблеми з сертифікатом, DNS або лімітами, які з’являться лише після деплою.

Опишіть очікувану поведінку callback в одному місці. Зазначте, яких статусів ви очікуєте, які з них запускають сповіщення користувачам, а які мають оновлювати лише внутрішні логи. Якщо провайдер повторює спроби через 30 секунд, також запишіть це. Майбутня діагностика буде швидшою, коли команда знає очікувану затримку.

Налаштуйте правило моніторингу для відсутніх callback. Один простий спосіб — позначати повідомлення, які залишаються в статусі sent довше за ваш звичайний проміжок. Інший — сповіщати, якщо endpoint callback повертає щось інше, ніж 200, більше 3 разів поспіль.

Якщо відстеження статусу SMS є частиною ширшої системи обміну повідомленнями, підтримуйте той самий рівень якості для всіх каналів. Команди часто поєднують SMS-тести з налаштуванням DKIM SPF DMARC для транзакційних листів, бо обидві системи залежать від перевірки ідентичності, доставки подій і зрозумілої обробки помилок. Одна сторона збоює тихо. Інша — голосно. Обидві потребують тестів.

І насамкінець, збережіть один приклад callback, який точно працює, у внутрішній документації. Додайте body запиту, заголовок підпису, код відповіді та сторінку події провайдера. Цей єдиний зразок стане вашим орієнтиром, коли майбутній реліз змінить структуру payload або оператор почне поводитися інакше.