Como testar SMS após configurar o Webhook: Passo a passo

Configurar notificações em tempo real para o seu negócio — seja enviando confirmações de consultas para uma clínica ou atualizações de pedidos para uma oficina — exige uma maneira confiável de rastrear o status de entrega. Depois de configurar sua URL de callback, saber exatamente como testar sms após configurar o webhook é o próximo passo crítico para garantir que seu sistema processe relatórios de entrega e mensagens recebidas sem falhas.

Passo 1: Configurar um Receptor de Webhook Local

Antes de testar como seu sistema lida com relatórios de entrega de SMS, você precisa de uma URL pública que possa receber requisições HTTP POST do seu gateway de SMS. Se você estiver desenvolvendo localmente, seu servidor rodando em localhost:3000 não está acessível à internet aberta. Para superar essa barreira, você pode usar ferramentas de tunelamento local como o ngrok, LocalTunnel ou ferramentas online de teste de webhook como o Webhook.site.

Para um teste rápido e sem configuração, o Webhook.site é altamente recomendado. Ele gera uma URL pública temporária e exclusiva onde você pode observar os payloads recebidos em tempo real. Se preferir testar diretamente contra sua aplicação local, execute o ngrok para expor sua porta local:

ngrok http 3000

Este comando gerará uma URL de encaminhamento HTTPS pública (ex: https://your-subdomain.ngrok-free.app). Você deve anexar sua rota de webhook a esta URL — por exemplo, https://your-subdomain.ngrok-free.app/webhooks/sms — e usá-la como seu endpoint de webhook.

Escrevendo um Receptor de Webhook Simples em Express.js

Se você quiser registrar e inspecionar o payload em seu próprio backend, aqui está um trecho simples de Node.js e Express para configurar um endpoint rápido:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/sms', (req, res) => {
  console.log('Received Webhook Payload:', JSON.stringify(req.body, null, 2));
  // Sempre retorne um status 200 OK rapidamente para confirmar o recebimento
  res.status(200).send({ status: 'success' });
});

app.listen(3000, () => console.log('Webhook receiver listening on port 3000'));

Passo 2: Configurar a URL do Webhook no seu Gateway de SMS

Assim que tiver sua URL pública de webhook, você deve registrá-la no painel do seu gateway de SMS. Ao contrário de provedores legados como Twilio ou Vonage, que exigem registros complexos de A2P 10DLC, verificação de perfil comercial e aprovações de campanha antes mesmo de você enviar uma mensagem de teste, o MySMSGate permite que você conecte seu próprio telefone Android via um simples código QR e comece a testar instantaneamente.

Para configurar seu webhook no MySMSGate:

1. Faça login no seu painel em MySMSGate.
2. Navegue até as configurações de API ou painel de Integração para Desenvolvedores.
3. Cole sua URL de webhook (ex: sua URL do Webhook.site ou sua URL de encaminhamento do ngrok) no campo "Webhook URL".
4. Selecione os eventos que deseja assinar (ex: sms.sent, sms.delivered, sms.failed ou sms.received).
5. Salve suas configurações.

Essa configuração faz a ponte entre seus cartões SIM físicos do Android e sua aplicação backend, garantindo que qualquer mudança de status de SMS ou mensagem de texto recebida seja instantaneamente encaminhada para seu servidor.

Passo 3: Disparar um SMS de Teste para Verificar a Entrega do Webhook

A maneira mais confiável de testar seu webhook é disparar uma mensagem SMS real. Com o MySMSGate, você não precisa comprar números virtuais ou configurar um ambiente de sandbox. Como a plataforma transforma seu telefone Android em um gateway de SMS, você envia mensagens reais através do seu próprio cartão SIM para o seu próprio número de celular para testes.

Você pode disparar um SMS de teste diretamente do painel web usando a interface Web Conversations, ou programmaticamente através da nossa API REST simples. Aqui está um exemplo de curl para disparar uma mensagem de teste:

curl -X POST https://mysmsgate.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999999999",
    "message": "Mensagem de teste de Webhook do MySMSGate",
    "sim_slot": 1
  }'

Após executar esta requisição, seu telefone Android conectado enviará imediatamente a mensagem via cartão SIM. Conforme a mensagem passa de "pendente" para "enviada" e finalmente "entregue", o MySMSGate disparará requisições HTTP POST para a URL do webhook configurada.

Passo 4: Inspecionar o Payload de Status de Entrega

Assim que disparar o SMS de teste, verifique seu receptor de webhook (como o Webhook.site ou seu terminal local rodando o ngrok). Você deverá ver uma requisição HTTP POST recebida. Inspecionar este payload é uma parte crítica de aprender como testar sms após configurar o webhook.

Um payload típico de webhook de status de entrega do MySMSGate se parece com este:

{
  "event": "sms.status_changed",
  "message_id": "msg_8f7d6e5c4b3a",
  "to": "+5511999999999",
  "status": "delivered",
  "sim_slot": 1,
  "device_id": "dev_android_01",
  "timestamp": "2026-08-05T14:32:01.000Z",
  "error_code": null
}

Ao analisar este payload, verifique os seguintes campos:

• message_id: Deve coincidir com o ID retornado pela chamada inicial da API.
• status: Confirma se a mensagem foi despachada ou entregue com sucesso.
• sim_slot: Identifica qual cartão SIM foi usado (especialmente útil para telefones Android dual-SIM).
• error_code: Se o status for "failed", este campo conterá o motivo (ex: sem sinal da operadora, sem créditos).

Passo 5: Testar Casos Extremos e Reentregas do Webhook

Uma aplicação de produção robusta deve lidar com mais do que apenas entregas bem-sucedidas. Você precisa verificar como seu sistema se comporta quando algo dá errado. Ao testar sua integração de webhook, certifique-se de simular e tratar estes três casos:

1. Simular uma Falha na Entrega: Envie um SMS para um número de telefone inválido ou desconectado. Observe o payload do webhook. O status deve atualizar para failed, e um error_code deve ser preenchido. No MySMSGate, qualquer SMS que falhe é automaticamente reembolsado no saldo da sua conta, o que você pode verificar no seu painel.
2. Simular Queda do Servidor: Desligue temporariamente seu servidor receptor de webhook local e dispare um SMS. Um bom gateway de SMS enfileirará os relatórios de entrega e tentará reenviá-los se seu servidor retornar um erro 5xx ou expirar o tempo (timeout). Verifique se o gateway tenta novamente a entrega do webhook assim que você trouxer seu servidor de volta online.
3. Lidar com Webhooks Duplicados: Em cenários raros de rede, seu servidor pode receber o mesmo evento de webhook duas vezes. Garanta que seu código de backend seja idempotente — o que significa que ele verifica se o status do message_id já foi atualizado no seu banco de dados antes de executar qualquer lógica de negócio (como enviar um e-mail de acompanhamento ou atualizar um registro de cliente).

Comparando Ambientes de Teste de Webhook de Gateways de SMS

Testar webhooks pode variar drasticamente dependendo do provedor de API de SMS que você escolher. Plataformas legadas de comunicação em nuvem costumam introduzir atritos através de regras de conformidade complexas e sandboxes, enquanto gateways modernos baseados em Android simplificam a experiência do desenvolvedor.

Abaixo está uma comparação entre testar webhooks e gerenciar a entrega de SMS em diferentes plataformas:

Ao usar seu próprio telefone Android como gateway de SMS, você evita a necessidade de comprar short codes dedicados caros ou números virtuais apenas para testar seus webhooks. Isso torna o MySMSGate a API de SMS mais barata para pequenas empresas que desejam notificações simples e confiáveis sem os custos fixos de contratos corporativos.

Perguntas Frequentes

Abaixo estão algumas das perguntas mais comuns que desenvolvedores e proprietários de empresas fazem ao configurar e testar webhooks de SMS.

Como verifico se meu endpoint de webhook está recebendo os status de entrega de SMS?

Você pode verificar isso checando os logs do seu servidor ou usando uma ferramenta como o Webhook.site. Quando um SMS é enviado, o gateway envia uma requisição HTTP POST para sua URL. Se os logs do seu servidor mostrarem uma requisição POST recebida com um código de resposta 200 OK, seu endpoint está recebendo os status de entrega com sucesso.

Quais ferramentas devo usar para testar webhooks localmente?

As melhores ferramentas para testes locais de webhook são o ngrok (para expor seu servidor local à internet através de um túnel seguro) e o Webhook.site (para inspecionar rapidamente payloads JSON brutos sem escrever código). Ambas as ferramentas são gratuitas e amplamente utilizadas por desenvolvedores.

Por que meu webhook de SMS está retornando um erro 500 durante os testes?

Um erro 500 Internal Server Error significa que o código do seu receptor de webhook falhou ou encontrou um erro ao processar o payload recebido. Verifique os logs do seu servidor backend para encontrar o stack trace. Certifique-se de que seu código está analisando corretamente o corpo JSON e retornando uma resposta 200 OK rapidamente, antes de realizar qualquer operação de banco de dados demorada.

Como o MySMSGate lida com as tentativas de reenvio do webhook se meu servidor ficar offline?

Se o seu servidor estiver offline ou retornar um status de erro (como 500 ou 503), o sistema de entrega de webhooks do MySMSGate enfileirará automaticamente a notificação e tentará reenviá-la em intervalos crescentes. Isso garante que você nunca perca relatórios de entrega críticos ou respostas recebidas de clientes durante breves atualizações de servidor.