Las pruebas locales de webhooks de Twilio te permiten recibir respuestas de SMS, callbacks de voz y actualizaciones de estado de mensajería en tu máquina local. Twilio envía los webhooks como peticiones HTTP POST con payloads codificados como formulario: tu localhost necesita una URL HTTPS pública para recibirlos durante el desarrollo.
Por qué los callbacks de Twilio requieren una URL pública
Cuando alguien envía un SMS a tu número de Twilio o completa una llamada de voz, Twilio hace un POST de los datos del evento a tu URL de webhook configurada. Las direcciones locales como http://localhost:3000/sms son inalcanzables desde la infraestructura de Twilio. Un túnel a localhost salva esa distancia con un endpoint HTTPS público.
Tipos de webhook de Twilio para probar en local
- SMS entrante: cuando un usuario envía un mensaje de texto a tu número de Twilio.
- Callbacks de estado de SMS: confirmaciones de entrega (sent, delivered, failed).
- Callbacks de voz: peticiones TwiML cuando se conecta una llamada o entra en un menú.
- Mensajería de WhatsApp: webhooks entrantes y de estado de la WhatsApp Business API.
- Conversations API: eventos de mensaje añadido y de participantes.
Paso a paso: probar webhooks de Twilio en local
- Inicia tu app local con rutas de webhook de Twilio (por ejemplo
/sms/inbound). - Ejecuta
npx portpreview 3000para generar una URL HTTPS pública. - En la Consola de Twilio, configura la URL de webhook de tu número de teléfono con la URL del túnel más la ruta.
- Configura el método HTTP (normalmente POST) y asegúrate de que el content type coincide con tu handler.
- Envía un SMS de prueba o haz una llamada de prueba para disparar el webhook.
- Inspecciona la petición capturada: Twilio envía payloads codificados como formulario, no JSON.
- Verifica que tu handler valida la firma de Twilio y devuelve TwiML válido o una respuesta 2xx.
Validar firmas de petición de Twilio en local
Twilio firma cada petición con una cabecera X-Twilio-Signature calculada a partir de la URL completa y los parámetros POST usando tu auth token. Tu handler debe:
- Usar la URL pública exacta (incluido el hostname del túnel) para validar la firma.
- Pasar todos los parámetros POST a la función de validación.
- Rechazar peticiones con firmas inválidas, incluso durante las pruebas locales.
Cuando tu URL de túnel cambie entre sesiones, actualiza tanto la URL de webhook en la Consola de Twilio como tu URL de validación.
Consejos de depuración específicos de Twilio
Payloads codificados como formulario
A diferencia de Stripe o GitHub, Twilio envía datos application/x-www-form-urlencoded. Asegúrate de que tu handler parsea los cuerpos de formulario correctamente, no solo JSON.
Respuestas TwiML
Los handlers de voz y SMS deben devolver XML TwiML válido. Prueba el formato de la respuesta en local antes de que Twilio marque las entregas como fallidas.
Comportamiento de timeout
Twilio espera respuestas en 15 segundos para la mayoría de los webhooks. Los handlers lentos provocan reintentos y entregas duplicadas: usa el replay de webhooks para probar el manejo de reintentos.
Cadenas de callbacks de estado
Los flujos de SMS suelen encadenar webhooks entrantes con callbacks de estado. Prueba ambos endpoints en local configurando rutas o paths de túnel separados.
Pruebas locales de Twilio vs. Twilio CLI
La CLI de Twilio puede simular peticiones entrantes con twilio phone-numbers:update y plugins de túnel locales. Un túnel a localhost dedicado con captura de peticiones te da visibilidad persistente de cada callback, capacidad de replay y un flujo que escala entre varios proveedores, no solo Twilio.
Para patrones generales de depuración de webhooks, lee cómo depurar webhooks en local.
Únete a la lista de espera de PortPreview para probar webhooks de Twilio y de varios proveedores desde un solo túnel.