Webhook de SMS na prática: status de entrega em tempo real
Depois de enviar um SMS via API, você precisa saber o que aconteceu com ele. Consultar o status em loop (polling) é ineficiente. A solução correta é o webhook.
O que é um webhook
Um webhook é um endpoint HTTP no seu servidor que o provedor chama automaticamente sempre que o status de uma mensagem muda — entregue, falhou ou respondido. Em vez de você perguntar, o sistema avisa.
Como configurar
Você cadastra a URL do seu endpoint no painel. A cada evento, o provedor faz um POST com um JSON contendo o id da mensagem, o novo status e um timestamp.
Segurança e idempotência
- Verifique a origem: valide uma assinatura ou um segredo compartilhado no header.
- Seja idempotente: o mesmo evento pode chegar mais de uma vez; trate por
id+ status para não duplicar efeitos. - Responda rápido: retorne 2xx imediatamente e processe de forma assíncrona.
Tratando cada status
Use entregue para confirmar o fluxo (ex.: marcar o OTP como enviado), falhou para acionar um retry ou rota alternativa, e respondido para fluxos de duas vias. Com webhooks confiáveis, sua infraestrutura para de adivinhar. Veja a documentação completa na SMSGo.