Webhook repetido e processamento em fila

O receptor de eventos recebeu duas vezes o mesmo aviso de pagamento, e a fila mostra duas mensagens iguais. A proposta de apagar a segunda mensagem e marcar a primeira como concluída decide sem saber o que já foi aplicado, e o caso mostra como acompanhar o evento da chegada até o efeito no banco.

O relato e as evidências

O site de vendas gerou o pedido PED-0002, e o serviço de pagamentos avisou o pagamento PAG-0002 pelo webhook. O suporte encontra duas chegadas do mesmo aviso e duas mensagens na fila, e o pedido continua na lista de atendimento, com o receio de uma baixa de estoque ou de um faturamento em dobro. Alguém propõe apagar a segunda mensagem e marcar a primeira como concluída. O receptor registra:

• 2026-10-07T11:00:00-03:00 evento=EVT-0002 pagamento=PAG-0002 pedido=PED-0002 chegada=1 resposta=200
• 2026-10-07T11:00:20-03:00 evento=EVT-0002 pagamento=PAG-0002 pedido=PED-0002 chegada=2 resposta=200

Pelo contrato, o serviço de pagamentos pode repetir um aviso e não garante a ordem de entrega. Ainda faltam a política de duplicidade da integração, o significado da resposta 200, o histórico do consumo e a situação do pedido no banco.

As duas chegadas têm a mesma identidade de evento e, por isso, não indicam dois pagamentos. Também não mostram quantas vezes o efeito foi aplicado. Continuam possíveis uma duplicata já descartada, mensagens ainda à espera, um processamento pela metade e um efeito repetido. Apagar uma entrega sem saber o que foi aplicado pode eliminar um trabalho ainda necessário, e o próximo passo é acompanhar o EVT-0002 da recepção até o efeito e a confirmação do consumo.

O que cada confirmação significa

A configuração da integração mostra a sequência do receptor: ele valida a assinatura, publica a mensagem em uma fila do RabbitMQ, espera a confirmação de publicação do broker e só então responde 200. O consumidor da fila usa o ack manual, enviado depois do COMMIT da transação local. O receptor não descarta duplicatas, e essa proteção fica com o consumidor, que grava a identidade de cada evento tratado.

Com essa configuração, a resposta 200 confirma a publicação na fila, e não a atualização do pedido, e o histórico do broker confirma as duas publicações. A confirmação de publicação e o ack do consumidor respondem a perguntas diferentes: a primeira diz que o broker recebeu a mensagem, e o segundo diz que o consumidor aceitou a entrega como tratada.

Outras configurações mudariam a leitura. Com a assinatura recusada, faltaria um aceite válido do aviso, e, sem a confirmação de publicação, seria preciso investigar uma publicação com o retorno perdido. Um ack automático, enviado no momento da entrega, também não provaria a transação concluída.

A queda entre o COMMIT e o ack

O histórico do consumidor mostra o tratamento da primeira mensagem:

• evento=EVT-0002 consumidor=consumidor-01 transacao=TX-0002 iniciada
• evento=EVT-0002 consumidor=consumidor-01 transacao=TX-0002 commit_confirmado
• consumidor=consumidor-01 conexao_encerrada antes_do_ack

No banco local, o pagamento PAG-0002 já aparece aplicado ao pedido, e a tabela de eventos tratados tem uma linha com o EVT-0002. A equipe de desenvolvimento confirma que as duas gravações acontecem na mesma transação e que a identidade do evento tem uma chave única. A primeira transação terminou, e a falha aconteceu antes do ack. Por isso, o broker entrega a mensagem de novo, com o trabalho já aplicado.

A reentrega não indica que a primeira transação foi desfeita. O consumidor, com a proteção da integração, reconhece a duplicata pela identidade gravada e confirma a entrega sem repetir o efeito. Sem um registro confiável da identidade, os efeitos precisariam ser reconciliados antes de qualquer novo processamento. Com a transação desfeita e nada aplicado, a mensagem ainda representaria um trabalho necessário.

A retomada e a conferência do efeito

Depois da retomada do consumidor, chegam a reentrega da primeira mensagem e a segunda publicação. Nas duas, o consumidor encontra a identidade do EVT-0002, registra a duplicata sem nova aplicação e confirma a entrega. A consulta final encontra um único efeito do pagamento PAG-0002 no pedido PED-0002, e a tela recarregada mostra o pedido pago, fora da lista de pendências.

A conferência vale para o efeito examinado. A baixa de estoque, o faturamento e as outras ações ligadas ao pedido têm identificadores e registros próprios, fora daquela transação, e cada uma precisa da própria conferência. O motivo da repetição pelo serviço de pagamentos também continua sem confirmação: o serviço pode não ter recebido a primeira resposta a tempo ou ter seguido outra regra prevista no contrato, e faltam os registros dele.

Se uma entrega tivesse ido para a DLQ, o motivo do desvio seria lido antes de qualquer devolução à fila. A DLQ não significa que a mensagem não foi aplicada, e a devolução de todas as mensagens não substitui a proteção contra a repetição.

O registro do atendimento

O registro separa a repetição do aviso da repetição do efeito:

• Ocorrência: o EVT-0002 chegou duas vezes ao receptor e gerou duas publicações confirmadas na fila;
• Evidências: a primeira transação do consumidor teve COMMIT, com o efeito e a identidade do evento gravados juntos, e a conexão caiu antes do ack;
• Tratamento: o consumidor reconheceu a reentrega e a segunda publicação pela identidade gravada e confirmou as entregas sem repetir o efeito, sem mensagens apagadas nem estados forçados;
• Validação: o banco e a tela mostram um único pagamento aplicado ao pedido PED-0002;
• Pendências: o motivo da repetição pelo serviço de pagamentos e a conferência própria do estoque e do faturamento do pedido.