Локальное тестирование вебхуков Twilio позволяет получать ответы по SMS, голосовые колбэки и обновления статуса сообщений прямо на вашей машине. Twilio отправляет вебхуки как HTTP-POST-запросы с form-encoded payload — вашему localhost нужен публичный HTTPS-URL, чтобы принимать их во время разработки.
Почему колбэкам Twilio нужен публичный URL
Когда кто-то отправляет SMS на ваш номер Twilio или завершает звонок, Twilio делает POST с данными события на настроенный URL вебхука. Локальные адреса вроде http://localhost:3000/sms недоступны из инфраструктуры Twilio. Туннель к localhost устраняет этот разрыв с помощью публичного HTTPS-эндпоинта.
Типы вебхуков Twilio для локального тестирования
- Входящие SMS: когда пользователь отправляет текстовое сообщение на ваш номер Twilio.
- Статус-колбэки SMS: подтверждения доставки (sent, delivered, failed).
- Голосовые колбэки: TwiML-запросы при подключении звонка или входе в меню.
- Мессенджинг WhatsApp: входящие и статусные вебхуки WhatsApp Business API.
- Conversations API: события добавления сообщения и участников.
Пошагово: локальное тестирование вебхуков Twilio
- Запустите локальное приложение с маршрутами вебхуков Twilio (например,
/sms/inbound). - Выполните
npx portpreview 3000, чтобы получить публичный HTTPS-URL. - В консоли Twilio задайте URL вебхука вашего номера как URL туннеля плюс путь маршрута.
- Настройте HTTP-метод (обычно POST) и убедитесь, что content type соответствует вашему обработчику.
- Отправьте тестовое SMS или сделайте тестовый звонок, чтобы запустить вебхук.
- Изучите захваченный запрос — Twilio отправляет form-encoded payload, а не JSON.
- Убедитесь, что обработчик валидирует подпись Twilio и возвращает корректный TwiML или ответ 2xx.
Проверка подписей запросов Twilio локально
Twilio подписывает каждый запрос заголовком X-Twilio-Signature, вычисленным из полного URL и POST-параметров с помощью вашего auth-token. Ваш обработчик должен:
- использовать точный публичный URL (включая хостнейм туннеля) для проверки подписи.
- передавать все POST-параметры в функцию валидации.
- отклонять запросы с недействительной подписью, даже при локальном тестировании.
Когда URL туннеля меняется между сессиями, обновляйте и URL вебхука в консоли Twilio, и ваш URL для валидации.
Советы по отладке, специфичные для Twilio
Form-encoded payload
В отличие от Stripe или GitHub, Twilio отправляет данные application/x-www-form-urlencoded. Убедитесь, что обработчик корректно парсит form-body, а не только JSON.
TwiML-ответы
Обработчики голоса и SMS должны возвращать корректный TwiML-XML. Тестируйте форматирование ответа локально, прежде чем Twilio пометит доставки как неудачные.
Поведение при таймауте
Для большинства вебхуков Twilio ожидает ответ в течение 15 секунд. Медленные обработчики вызывают повторы и дублирующие доставки — используйте повтор вебхуков для тестирования обработки повторов.
Цепочки статус-колбэков
SMS-воркфлоу часто связывают входящие вебхуки со статус-колбэками. Тестируйте оба эндпоинта локально, настроив отдельные маршруты или пути туннеля.
Локальное тестирование Twilio против Twilio CLI
Twilio CLI может имитировать входящие запросы через twilio phone-numbers:update и локальные туннельные плагины. Выделенный туннель к localhost с захватом запросов даёт постоянную видимость каждого колбэка, возможность повтора и воркфлоу, масштабируемый на нескольких провайдеров — не только на Twilio.
Об общих паттернах отладки вебхуков читайте в как отлаживать вебхуки локально.
Присоединяйтесь к листу ожидания PortPreview для тестирования вебхуков Twilio и других провайдеров из одного туннеля.