Lokalne testowanie webhooków Twilio pozwala odbierać odpowiedzi SMS, callbacki głosowe i aktualizacje statusu wiadomości na lokalnej maszynie. Twilio wysyła webhooki jako żądania HTTP POST z payloadami zakodowanymi jako formularz — twój localhost potrzebuje publicznego adresu HTTPS, aby je odbierać podczas developmentu.
Dlaczego callbacki Twilio wymagają publicznego URL
Gdy ktoś wysyła SMS na twój numer Twilio lub kończy połączenie głosowe, Twilio wysyła dane zdarzenia metodą POST na skonfigurowany adres webhooka. Lokalne adresy jak http://localhost:3000/sms są nieosiągalne z infrastruktury Twilio. Tunel do localhost wypełnia tę lukę publicznym endpointem HTTPS.
Typy webhooków Twilio do testowania lokalnie
- SMS przychodzący: gdy użytkownik wysyła wiadomość tekstową na twój numer Twilio.
- Callbacki statusu SMS: potwierdzenia dostarczenia (sent, delivered, failed).
- Callbacki głosowe: żądania TwiML, gdy połączenie się łączy lub wchodzi do menu.
- Wiadomości WhatsApp: przychodzące i statusowe webhooki WhatsApp Business API.
- Conversations API: zdarzenia dodania wiadomości i uczestników.
Krok po kroku: lokalne testowanie webhooków Twilio
- Uruchom lokalną aplikację z trasami webhooków Twilio (na przykład
/sms/inbound). - Wykonaj
npx portpreview 3000, aby wygenerować publiczny adres HTTPS. - W konsoli Twilio ustaw adres webhooka swojego numeru na adres tunelu plus ścieżkę trasy.
- Skonfiguruj metodę HTTP (zwykle POST) i upewnij się, że content type pasuje do twojego handlera.
- Wyślij testowy SMS lub wykonaj testowe połączenie, aby wyzwolić webhook.
- Sprawdź przechwycone żądanie — Twilio wysyła payloady zakodowane jako formularz, nie JSON.
- Zweryfikuj, że handler waliduje podpis Twilio i zwraca prawidłowy TwiML lub odpowiedź 2xx.
Walidacja podpisów żądań Twilio lokalnie
Twilio podpisuje każde żądanie nagłówkiem X-Twilio-Signature obliczonym z pełnego URL i parametrów POST za pomocą twojego auth tokena. Twój handler powinien:
- Używać dokładnego publicznego URL (łącznie z nazwą hosta tunelu) do walidacji podpisu.
- Przekazywać wszystkie parametry POST do funkcji walidującej.
- Odrzucać żądania z nieprawidłowymi podpisami, nawet podczas testów lokalnych.
Gdy adres tunelu zmienia się między sesjami, zaktualizuj zarówno adres webhooka w konsoli Twilio, jak i adres używany do walidacji.
Wskazówki debugowania specyficzne dla Twilio
Payloady zakodowane jako formularz
W przeciwieństwie do Stripe czy GitHub, Twilio wysyła dane application/x-www-form-urlencoded. Upewnij się, że handler poprawnie parsuje ciała formularzy, nie tylko JSON.
Odpowiedzi TwiML
Handlery głosu i SMS muszą zwracać prawidłowy XML TwiML. Testuj formatowanie odpowiedzi lokalnie, zanim Twilio oznaczy dostawy jako nieudane.
Zachowanie przy timeout
Twilio oczekuje odpowiedzi w ciągu 15 sekund dla większości webhooków. Wolne handlery powodują ponowienia i zduplikowane dostawy — użyj powtórki webhooków, aby przetestować obsługę ponowień.
Łańcuchy callbacków statusu
Przepływy SMS często łączą przychodzące webhooki z callbackami statusu. Testuj oba endpointy lokalnie, konfigurując osobne trasy lub ścieżki tunelu.
Lokalne testowanie Twilio a Twilio CLI
Twilio CLI potrafi symulować przychodzące żądania poleceniem twilio phone-numbers:update i lokalnymi pluginami tunelowymi. Dedykowany tunel do localhost z przechwytywaniem żądań daje trwałą widoczność każdego callbacku, możliwość powtórki i workflow skalujący się na wielu dostawców — nie tylko Twilio.
Ogólne wzorce debugowania webhooków znajdziesz w jak debugować webhooki lokalnie.
Dołącz do listy oczekujących PortPreview, aby testować webhooki Twilio i wielu dostawców z jednego tunelu.