Kiểm thử webhook Twilio trên máy cục bộ cho phép bạn nhận phản hồi SMS, callback thoại và cập nhật trạng thái nhắn tin ngay trên máy mình. Twilio gửi webhook dưới dạng request HTTP POST với payload mã hóa form — localhost của bạn cần một URL HTTPS công khai để nhận chúng khi phát triển.
Vì sao callback của Twilio cần URL công khai
Khi ai đó gửi SMS tới số Twilio của bạn hoặc hoàn tất một cuộc gọi thoại, Twilio POST dữ liệu sự kiện tới URL webhook bạn đã cấu hình. Các địa chỉ cục bộ như http://localhost:3000/sms không thể truy cập từ hạ tầng của Twilio. Một tunnel localhost bắc cầu khoảng cách đó bằng một endpoint HTTPS công khai.
Các loại webhook Twilio nên kiểm thử cục bộ
- SMS đến: khi người dùng gửi tin nhắn văn bản tới số Twilio của bạn.
- Callback trạng thái SMS: xác nhận gửi (sent, delivered, failed).
- Callback thoại: các request TwiML khi cuộc gọi kết nối hoặc vào menu.
- Nhắn tin WhatsApp: webhook đến và trạng thái của WhatsApp Business API.
- Conversations API: sự kiện thêm tin nhắn và người tham gia.
Từng bước: kiểm thử webhook Twilio cục bộ
- Khởi chạy app cục bộ với các route webhook Twilio (ví dụ
/sms/inbound). - Chạy
npx portpreview 3000để tạo URL HTTPS công khai. - Trong Twilio Console, đặt URL webhook của số điện thoại thành URL tunnel cộng với đường dẫn route.
- Cấu hình phương thức HTTP (thường là POST) và đảm bảo content type khớp với handler của bạn.
- Gửi một SMS test hoặc thực hiện một cuộc gọi test để kích hoạt webhook.
- Kiểm tra request đã bắt — Twilio gửi payload mã hóa form, không phải JSON.
- Xác minh handler của bạn xác thực chữ ký Twilio và trả về TwiML hợp lệ hoặc phản hồi 2xx.
Xác minh chữ ký request Twilio cục bộ
Twilio ký mỗi request bằng header X-Twilio-Signature được tính từ URL đầy đủ và các tham số POST bằng auth token của bạn. Handler của bạn nên:
- Dùng đúng URL công khai (bao gồm hostname của tunnel) để xác minh chữ ký.
- Truyền tất cả tham số POST vào hàm xác thực.
- Từ chối request có chữ ký không hợp lệ, kể cả khi kiểm thử cục bộ.
Khi URL tunnel đổi giữa các phiên, hãy cập nhật cả URL webhook trong Twilio Console lẫn URL dùng để xác thực.
Mẹo gỡ lỗi riêng cho Twilio
Payload mã hóa form
Khác với Stripe hay GitHub, Twilio gửi dữ liệu application/x-www-form-urlencoded. Đảm bảo handler parse đúng body dạng form, không chỉ JSON.
Phản hồi TwiML
Handler thoại và SMS phải trả về XML TwiML hợp lệ. Kiểm thử định dạng phản hồi cục bộ trước khi Twilio đánh dấu các lần gửi là thất bại.
Hành vi timeout
Twilio mong đợi phản hồi trong 15 giây với hầu hết webhook. Handler chậm gây retry và gửi trùng — dùng replay webhook để kiểm thử việc xử lý retry.
Chuỗi callback trạng thái
Luồng SMS thường nối webhook đến với callback trạng thái. Kiểm thử cả hai endpoint cục bộ bằng cách cấu hình các route hoặc path tunnel riêng.
Kiểm thử Twilio cục bộ so với Twilio CLI
Twilio CLI có thể giả lập request đến bằng twilio phone-numbers:update và các plugin tunnel cục bộ. Một tunnel localhost chuyên dụng có bắt request cho bạn khả năng quan sát liên tục mọi callback, khả năng replay và quy trình mở rộng được trên nhiều nhà cung cấp — không chỉ Twilio.
Về các mẫu gỡ lỗi webhook chung, hãy đọc cách gỡ lỗi webhook cục bộ.
Tham gia danh sách chờ PortPreview để kiểm thử webhook Twilio và nhiều nhà cung cấp từ một tunnel.