Webhook ou consulta em laço: como esperar o SMS

Existe um trecho de código que quase toda integração de SMS tem na primeira versão, e que quase nenhuma mantém na terceira:

while (true) {
  const sms = await buscarSms(pedidoId);
  if (sms) break;
  await esperar(1000);
}

Funciona. Você testa com um pedido, o código chega, o laço sai. O problema aparece depois, e não aparece como erro.

Por que o laço não escala

Suponha trinta seguntos de espera média e um pedido. São trinta requisições, vinte e nove delas devolvendo "ainda nada".

Agora suponha trezentos pedidos ao mesmo tempo. São nove mil requisições em trinta segundos, quase todas inúteis. Você construiu um gerador de tráfego que só serve para perguntar.

Três consequências, na ordem em que costumam doer:

Limite de taxa. A API começa a recusar. E ela recusa tudo, inclusive a criação de pedidos novos — a espera de um cliente derruba a compra de outro.

Latência que piora sozinha. Com o intervalo de um segundo, o código pode ficar até um segundo parado depois de já ter chegado. Para reduzir isso você diminui o intervalo, o que multiplica as requisições, o que aproxima o limite.

Processo preso. Cada laço segura um processo ou uma conexão. Trezentos laços simultâneos consomem recursos que não estão fazendo trabalho nenhum.

Webhook inverte a pergunta

Em vez de você perguntar, o servidor avisa. Você registra uma URL, e quando o SMS chega, a plataforma faz um POST para ela.

Zero requisição desperdiçada. A latência é a da entrega, não a do seu intervalo. E nada fica preso esperando.

O custo é que você precisa de um endereço público que receba POST — o que é trivial em servidor e chato em máquina de desenvolvimento. Para desenvolver, um túnel local resolve.

Três coisas que quebram webhook, e como evitar

Responder devagar. Se o seu endpoint processa antes de responder, ele demora, e a plataforma trata como falha e reenvia. Responda 200 primeiro, processe depois, em fila.

Não tolerar repetição. Entrega é ao menos uma vez, não exatamente uma vez. O mesmo aviso pode chegar duas vezes por retentativa ou por rede instável. Se o seu código libera um cadastro a cada aviso, ele vai liberar dois. Guarde o identificador do evento e ignore o que já processou.

Confiar no corpo sem verificar. A URL é pública: qualquer um pode fazer POST nela. Valide a assinatura antes de agir. Um endpoint que aceita qualquer corpo é um endpoint que qualquer um usa para dizer que o SMS chegou.

Onde SSE entra

SSE é uma conexão aberta que recebe o evento assim que ele existe. Também não desperdiça requisição, mas segura uma conexão.

Ele é para quando existe uma pessoa esperando na tela. O usuário comprou um número, está olhando, quer ver o código aparecer. SSE entrega isso sem recarregar a página e sem intervalo.

O que não fazer: usar SSE em processo de servidor. Um cliente que abre trezentas conexões e as mantém pendentes tem o mesmo problema de recurso do laço, com mais complexidade.

A regra

Situação	Use
Pessoa esperando na tela	SSE
Processo automático, servidor	Webhook
Rascunho, teste manual, uma vez	Consulta direta

Se você está em dúvida entre SSE e webhook, pergunte se alguém vai perceber a diferença de dois segundos. Se ninguém está olhando, é webhook.

Como fica na prática

Registre a URL em Webhooks, no painel. Ao criar o pedido, guarde o identificador. Quando o aviso chegar, confira a assinatura, responda 200 na hora, e trate o código na sua fila.

Para o passo a passo com os campos do evento, veja a documentação de webhooks. Para entender o produto por trás, a página de números virtuais.