Notificações de pedidos pelo WhatsApp sem mensagens duplicadas

Publicado em 2026-11-14 por frfrand

Arquitetura de eventos e idempotência para avisos de compra, envio e incidentes por WhatsApp.

# Notificações de pedidos por WhatsApp sem mensagens duplicadas

Uma loja altera o status de um pedido e dispara um evento. Se o webhook se repetir, o worker for reiniciado ou o provedor responder após um timeout, o sistema pode emitir dois avisos idênticos. Um evento 'processado' nem sempre equivale a uma entrega efetiva. É preciso distinguir os estados de negócio, as tentativas de envio e a aceitação do provedor.

O que notificar

Selecione eventos que realmente agreguem valor: pedido confirmado, pagamento creditado, preparado, entregue ao transportador, exceção de envio, entrega concluída e devolução. Evite enviar notificações por cada atualização interna ou microestado. O texto deve incluir referência reconhecível, status confirmado e uma ação útil; não dados de pagamento nem segredos.

Modelo de outbox

Quando uma operação altera o status no banco de dados, crie na mesma transação um registro de notificação pendente com uma chave única, por exemplo pedido_id + tipo_evento + versão_status + canal. Um worker processa essa outbox em segundo plano. Dessa forma, o evento não se perde se o aplicativo cair após salvar o pedido, antes de enviar a mensagem.

Máquina de estados

Use pendente, enviando, aceito, entregue, falha definitiva e requer revisão. Para um timeout incerto, consulte o status do provedor ou reconcilie antes de reenviar; a tentativa cega pode duplicar mensagens se a primeira tentativa realmente saiu. Mantenha um identificador de correlação e, se disponível, o ID da mensagem remota.

Modelos e preferências

Fora da janela de atendimento, utilize modelos adequados à categoria e regras vigentes. Verifique o consentimento e as preferências do cliente, separando notificações transacionais de marketing. Um pedido de cancelamento comercial não deve ser reativado automaticamente por um pedido subsequente sem fundamento.

Observabilidade e métricas

Meça a taxa de eventos duplicados bloqueados, fila pendente, latência até a aceitação, erros por modelo, entregas e cancelamentos. Estabeleça alertas por acúmulo e uma caixa de revisão para erros permanentes, como número inválido. Limite o volume por destinatário e evite inundações se forem importados pedidos históricos.

Teste de falhas

Execute o mesmo webhook 10 vezes, desconecte o provedor, corte um worker entre estados e envie eventos fora de ordem. O resultado esperado é uma única intenção de aviso por mudança de negócio, com rastreabilidade. Amplie a implementação com webhooks seguros e tarefas em segundo plano.

Perguntas frequentes

É necessário construir tudo sob medida? Nem sempre. Comece com o processo mínimo e adicione integrações quando existir uma necessidade demonstrável.

Como evitar erros repetidos? Com identificadores estáveis, validações, registros e testes de retentativas.

Quando intervir manualmente? Diante de dados ambíguos, erros persistentes e ações de alto impacto.

Conclusão

Documente o processo e teste suas falhas antes de ampliar o volume. Em ArduMaker você pode explorar a infraestrutura e as integrações aplicáveis a este cenário.

  • WhatsApp
  • ecommerce
  • webhooks
  • idempotencia

Continuar lendo

Todos os artigos · Planos VPS