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.