O teste local de webhooks do Twilio permite receber respostas de SMS, callbacks de voz e atualizações de status de mensagens na sua máquina local. O Twilio envia webhooks como requisições HTTP POST com payloads codificados como formulário — seu localhost precisa de uma URL HTTPS pública para recebê-los durante o desenvolvimento.
Por que os callbacks do Twilio exigem uma URL pública
Quando alguém envia um SMS para o seu número do Twilio ou conclui uma chamada de voz, o Twilio faz um POST dos dados do evento para a URL de webhook configurada. Endereços locais como http://localhost:3000/sms são inacessíveis pela infraestrutura do Twilio. Um túnel para localhost preenche essa lacuna com um endpoint HTTPS público.
Tipos de webhook do Twilio para testar localmente
- SMS de entrada: quando um usuário envia uma mensagem de texto para o seu número do Twilio.
- Callbacks de status de SMS: confirmações de entrega (sent, delivered, failed).
- Callbacks de voz: requisições TwiML quando uma chamada conecta ou entra em um menu.
- Mensagens do WhatsApp: webhooks de entrada e de status da WhatsApp Business API.
- Conversations API: eventos de mensagem adicionada e de participantes.
Passo a passo: testar webhooks do Twilio localmente
- Inicie seu app local com rotas de webhook do Twilio (por exemplo
/sms/inbound). - Execute
npx portpreview 3000para gerar uma URL HTTPS pública. - No Console do Twilio, defina a URL de webhook do seu número de telefone como a URL do túnel mais o caminho da rota.
- Configure o método HTTP (geralmente POST) e garanta que o content type combine com o seu handler.
- Envie um SMS de teste ou faça uma chamada de teste para disparar o webhook.
- Inspecione a requisição capturada — o Twilio envia payloads codificados como formulário, não JSON.
- Verifique se o handler valida a assinatura do Twilio e retorna TwiML válido ou uma resposta 2xx.
Validar assinaturas de requisição do Twilio localmente
O Twilio assina cada requisição com um cabeçalho X-Twilio-Signature calculado a partir da URL completa e dos parâmetros POST usando o seu auth token. Seu handler deve:
- Usar a URL pública exata (incluindo o hostname do túnel) para validar a assinatura.
- Passar todos os parâmetros POST para a função de validação.
- Rejeitar requisições com assinaturas inválidas, mesmo durante os testes locais.
Quando sua URL de túnel mudar entre sessões, atualize tanto a URL de webhook no Console do Twilio quanto a sua URL de validação.
Dicas de depuração específicas do Twilio
Payloads codificados como formulário
Diferente do Stripe ou do GitHub, o Twilio envia dados application/x-www-form-urlencoded. Garanta que o seu handler faça o parse de corpos de formulário corretamente, não só JSON.
Respostas TwiML
Handlers de voz e SMS precisam retornar XML TwiML válido. Teste a formatação da resposta localmente antes que o Twilio marque as entregas como falhas.
Comportamento de timeout
O Twilio espera respostas em 15 segundos para a maioria dos webhooks. Handlers lentos causam retentativas e entregas duplicadas — use o replay de webhook para testar o tratamento de retentativas.
Cadeias de callbacks de status
Fluxos de SMS costumam encadear webhooks de entrada com callbacks de status. Teste os dois endpoints localmente configurando rotas ou caminhos de túnel separados.
Teste local do Twilio vs. Twilio CLI
A CLI do Twilio pode simular requisições de entrada com twilio phone-numbers:update e plugins de túnel locais. Um túnel para localhost dedicado com captura de requisições dá a você visibilidade persistente de cada callback, capacidade de replay e um fluxo que escala por vários provedores — não só o Twilio.
Para padrões gerais de depuração de webhooks, leia como depurar webhooks localmente.
Entre na lista de espera do PortPreview para testar webhooks do Twilio e de vários provedores a partir de um único túnel.