Локальне тестування вебхуків 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 та інших провайдерів з одного тунелю.