Как тестировать callback-и статуса доставки SMS

Что такое callback-и статуса доставки SMS

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

Это различие важно. Сообщение может быть «отправлено» и при этом так и не дойти до телефона. Callback может прийти через несколько секунд, а может — после задержки со стороны оператора в несколько минут, в зависимости от маршрута и политики повторных попыток у провайдера.

Думайте о callback-е как о цепочке подтверждений, а не о самом подтверждении. Ответ API на запрос отправки обычно доказывает, что провайдер взял задачу в работу. Callback доказывает, что произошло дальше, а именно это и нужно тестировать, если ваше приложение зависит от обновлений статуса для уведомлений, квитанций или процессов поддержки клиентов. На практике такое тестирование callback статуса доставки SMS помогает заранее увидеть, как система поведет себя при реальной задержке оператора.

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

Что нужно подготовить перед тестированием callback-ов

Перед тем как тестировать callback-и статуса доставки SMS, вам понадобятся четыре вещи: аккаунт у SMS-провайдера, URL для callback-а, доступ к серверным логам и тестовый номер. Лучше всего использовать телефон, который вы контролируете. Так тест будет воспроизводимым и не придется гадать о поведении оператора.

Подготовьте публичный HTTPS-endpoint, даже если сейчас он просто записывает запросы в лог. Многие провайдеры не принимают обычный HTTP для доставки callback-ов, а некоторые тестовые среды блокируют приватные адреса. Вам также нужен способ просматривать заголовки запроса, тело и коды ответа от сервера.

Держите панель провайдера открытой. Там вы будете сверять идентификаторы сообщений, временные метки и события статуса. Если у провайдера есть повторный прогон webhook-ов или история событий, включите это до начала теста. Это сэкономит время позже, если callback придет дважды или не придет вовсе.

Если ваш SMS-процесс является частью более крупной системы сообщений, полезно проверить и связанные сценарии обработки событий, например email webhook-события для транзакционных писем. Механика в одном важном смысле похожа: ваш сервер должен быстро принимать и проверять полезные данные события, а затем сохранять их до того, как сработает повторная попытка.

Шаг 1: Настройте тестовый endpoint для callback-ов

Создайте отдельный endpoint для callback-ов, например /sms-status, вместо того чтобы отправлять их в общий API-маршрут. Небольшой специализированный endpoint упрощает тестирование, потому что каждый запрос относится к одной задаче. Вы можете логировать сырой body, заголовки, время ответа и любые ошибки парсинга в одном месте.

Сделайте endpoint публичным и HTTPS. Используйте сертификат, которому доверяет ваш провайдер. Если провайдер не может достучаться до URL, callback завершится ошибкой еще до того, как выполнится ваш код. Это кажется очевидным, но именно на этом чаще всего ломаются первые тесты.

Возвращайте быстрый ответ 200 после сохранения полезной нагрузки. Не ждите отчета из базы данных или вызова внешнего сервиса. Endpoint для callback-а должен сначала подтвердить получение, а уже потом выполнять дополнительную работу. Медленный ответ может вызвать повторные попытки, а они только запутают результаты теста.

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

Шаг 2: Отправьте тестовую SMS с включенным отслеживанием callback-ов

Используйте API или панель провайдера, чтобы отправить тестовое сообщение и указать URL callback-а в запросе на отправку или в настройках аккаунта. Некоторые провайдеры называют это status callback, delivery receipt URL или webhook endpoint. Название меняется, функция — нет.

Убедитесь, что отслеживание callback-ов включено именно для этого сообщения. Запрос на отправку может пройти успешно, даже если доставка событий не активна. Если провайдер поддерживает флаги на уровне отдельного сообщения, задайте их явно, чтобы не полагаться на значение по умолчанию, которое может отличаться в зависимости от аккаунта или среды.

Используйте свой тестовый номер. Сначала отправьте короткое сообщение, например предупреждение из шести слов. Короткий текст проще заметить на телефоне и проще сопоставить с логами провайдера. Один лишний символ может иметь значение, если вы тестируете объединение сообщений или кодировку, поэтому первый тест лучше сделать максимально простым.

Если ваша система уже обрабатывает другие webhook-события, тот же подход остается важным. Команды, которые уже используют инструменты тестирования доставляемости email · YourTrend, часто быстрее осваивают тесты SMS, потому что привычка одна и та же: сначала фиксировать точный запрос, а потом сравнивать его с тем, что видно у поставщика, вместо того чтобы полагаться на память. Именно здесь особенно полезно заранее понять, как проверить delivery receipt SMS в вашей среде и какие поля при этом меняются.

Шаг 3: Проверьте основные состояния доставки

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

Проще всего обычно вызвать состояние queued. Отправьте тестовую SMS и следите за callback-ом на начальный статус. Провайдер может сначала пометить сообщение как принятое, а затем обновить его, когда оно выйдет из очереди. Если вы ловите только первое событие, ваша логика может пропустить последующий переход.

Чтобы вызвать failed или undelivered, используйте номер, который неверен, неактивен или недоступен в сети оператора — в зависимости от правил тестирования вашего провайдера. Некоторые провайдеры также предлагают sandbox-номера или коды симуляции, которые принудительно задают определенные состояния. Это удобно, потому что снижает неопределенность.

Delivered — это состояние, которое волнует людей больше всего, но именно его нельзя считать само собой разумеющимся. Телефон должен быть доступен, сеть должна вернуть отчет о доставке, а провайдер должен преобразовать этот отчет в callback. Три звена. Одного сбоя достаточно.

Sent — это не то же самое, что delivered. Состояние sent часто означает, что провайдер передал сообщение оператору или как минимум попытался доставить его. Если ваш бизнес-процесс начинает отсчет от «sent», вы можете обещать пользователю то, чего на самом деле еще не произошло.

Шаг 4: Проверьте полезную нагрузку callback-а

Откройте тело запроса и проверьте каждое поле, которое обещает провайдер. Идентификаторы сообщений должны совпадать с исходным ответом на отправку. Временные метки должны соответствовать часовому поясу вашего аккаунта или UTC — в зависимости от того, как их форматирует провайдер. Значения статусов должны оставаться в наборе, описанном провайдером.

Посмотрите на данные отправителя и получателя. Тестовое сообщение, отправленное с одного номера, должно возвращаться в callback-е с тем же номером назначения, если только провайдер не маскирует или не нормализует его. Если payload включает коды оператора, причины ошибок или направление сообщения, сохраняйте и их тоже. Позже они пригодятся, когда клиент скажет: «Я его так и не получил».

Заголовки подписи заслуживают особого внимания. Многие провайдеры подписывают callback-и, чтобы ваш сервер мог убедиться, что запрос действительно пришел от них. Проверьте точное имя заголовка, алгоритм подписи и схему с общим секретом или публичным ключом. Если вы пропустите проверку на этапе тестирования, вы не тестируете тот же путь, который будете использовать в production. Для команд, которые уже внедрили SMS webhook status callback, это обычно значит, что верификация подписи должна быть частью каждого прогона.

Используйте одну проверку для структуры и одну для подлинности. Сначала убедитесь, что JSON или form-body корректно парсится. Затем проверьте, что подпись или токен совпадают с тем, что ожидает провайдер. Такой двухэтапный контроль ловит и некорректные payload-ы, и поддельные запросы.

Шаг 5: Сверьте логи провайдера с логами вашего webhook-а

Теперь сопоставьте историю событий у провайдера с тем, что получил ваш сервер. Сначала используйте message ID. Затем сравните status, timestamp и количество повторных попыток. Если с одной стороны видно три события, а с другой — только два, это расхождение стоит исправить до того, как кто-то назовет его проблемой production.

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

Если провайдер позволяет выгружать логи, забирайте их в том же тестовом окне. Пауза в десять минут между отправкой сообщений может облегчить сравнение логов. Смысл не только в том, чтобы увидеть, что callback пришел, а в том, чтобы доказать, что ваш сервер и провайдер одинаково понимают, какое событие произошло и когда.

Для команд, которые уже сравнивают почтовые события, это будет знакомо. Тот же подход, который используется для лучших практик обработки email bounce, работает и здесь: не доверяйте только счастливому сценарию. Сверяйте запись у поставщика, запись о приеме у себя и конечное состояние, которое сохранило ваше приложение.

Шаг 6: Разберитесь с отсутствующими или неверными callback-ами

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

Далее проверьте таймауты. Если сервер слишком долго отвечает, провайдер может повторить попытку или пометить callback как неудачный. Держите обработчик коротким. Сначала сохраните payload, верните 200, а остальное обработайте позже.

Правила файрвола могут заблокировать запрос еще до того, как его увидит ваш код. То же могут сделать IP allowlist-ы, правила WAF или basic auth, который провайдер не может пройти. Если вашему endpoint нужна аутентификация, убедитесь, что провайдер поддерживает именно тот метод, который вы выбрали. Одни системы поддерживают секрет в query string, другие отправляют заголовок authorization, а некоторые делают и то и другое.

Некорректный JSON обычно означает, что провайдер использовал другой content type, чем вы ожидали, или ваш парсер отверг форму поля, которую вы не тестировали. Смотрите на сырой body. Не полагайтесь только на красиво отформатированную версию. Отсутствующая запятая в вашем собственном коде тоже может создать впечатление, что проблема на стороне провайдера.

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

Если подписи не проходят проверку, сравните точные байты, которые были отправлены, с байтами, которые использовал ваш верификатор. Кодировка символов, переносы строк и парсинг тела могут изменить результат. Это одна из причин, почему то, как проверить callback-и статуса доставки SMS, требует шага с сырым запросом, а не только с разобранным объектом.

Шаг 7: Подтвердите готовность к production

Повторите полный тест в staging или в окружении, максимально похожем на production, с реальным HTTPS, тем же кодовым путем и тем же местом назначения логов. Используйте живой аккаунт провайдера, если тестовый аккаунт ведет себя иначе. Фальшивая среда может скрыть проблемы с сертификатом, DNS или лимитами, которые проявятся только после деплоя.

Опишите ожидаемое поведение callback-ов в одном месте. Укажите, каких статусов вы ждете, какие из них вызывают уведомления пользователю, а какие должны только обновлять внутренние логи. Если провайдер делает повторные попытки через 30 секунд, тоже запишите это. Будущая отладка станет быстрее, когда команда знает ожидаемую задержку.

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

Если отслеживание статусов SMS является частью более широкой системы сообщений, придерживайтесь того же уровня качества и в других каналах. Команды часто объединяют тесты SMS с настройкой DKIM SPF DMARC для транзакционных писем, потому что обе системы зависят от проверки идентичности, доставки событий и понятной обработки ошибок. Одна сторона ломается тихо. Другая — громко. Обе заслуживают тестирования.

И наконец, сохраните один пример заведомо корректного callback-а во внутренней документации. Включите тело запроса, заголовок подписи, код ответа и страницу события у провайдера. Этот образец станет ориентиром, когда будущий релиз изменит структуру payload-а или оператор начнет вести себя иначе.