Usamos cookies para medir audiência e melhorar sua experiência. Você pode aceitar ou recusar a qualquer momento. Veja sobre o iMasters.
Imagine um webhook de pagamento que habilita o acesso a um curso. O servidor recebe a notificação, grava o acesso e perde a conexão antes de responder. Para quem enviou o evento, aquele silêncio permite uma nova entrega. Para o seu sistema, a matrícula já existe. Se a segunda entrega também dispara e-mail e gera lançamento de auditoria, o cliente pode receber duas confirmações sem ter comprado duas vezes. Uma fila separa responsabilidades, mas a duplicidade continua existindo se duas mensagens representarem a mesma operação.
A primeira decisão é dar um nome estável ao evento: use o identificador fornecido pelo emissor, associado à conta de origem. Duas contas podem usar o mesmo identificador sem representar a mesma entrega. Preserve também a distinção entre evento recebido e efeito aplicado. Um pagamento pode chegar em mais de um evento legítimo, como confirmação e estorno. Deduplicar apenas pelo identificador do pagamento descartaria uma transição válida. Deduplicar pelo identificador de entrega, por sua vez, pode ser insuficiente se vários eventos válidos pedirem a mesma matrícula.
Eu usaria duas tabelas: uma caixa de entrada com chave única por origem e evento, e uma tabela de tarefas pendentes. Ao receber a notificação, o código Node.js valida o evento e abre a transação. Tenta registrar o evento na caixa de entrada. Se o registro for novo, grava na mesma transação a tarefa que o consumidor precisa buscar. Só envia a resposta de sucesso depois do commit. Se o banco estiver indisponível, a API devolve erro transitório conforme o contrato do emissor.
A chave única é importante porque consultas do tipo “procure e, se faltar, insira” podem correr em paralelo. Duas entregas podem observar a ausência da linha antes que qualquer gravação aconteça. A restrição no banco arbitra essa disputa no ponto em que os dados são gravados. A entrega que encontra a linha existente pode receber a resposta de sucesso já esperada, sem criar outra tarefa. Uma linha existente com o mesmo identificador e conteúdo incompatível merece registro para investigação: vale distinguir uma repetição normal de um conflito nos dados de origem.
Suponha que a tarefa já esteja na fila. O consumidor grava a matrícula, mas para antes de marcar o trabalho como concluído. Quando outro processo pegar a mesma tarefa, ele precisa conseguir avançar com segurança. Para a matrícula, uma restrição por aluno e curso pode bastar, desde que o domínio só permita uma matrícula naquele par. O e-mail de confirmação precisa de uma chave própria, pois seu efeito ocorre fora do banco. Quando o serviço externo aceita uma chave de idempotência, reutilize a mesma em todas as tentativas daquela confirmação.
Quando o serviço externo não oferece esse recurso, existe uma janela de incerteza após o envio. Registrar a tentativa antes de chamar o serviço ajuda a investigar, mas não comprova que a mensagem foi entregue. Se o cliente perder a resposta, procure primeiro um identificador rastreável ou um estado consultável no provedor. Caso esse estado não exista, combine com o produto qual consequência é mais tolerável naquele ponto: uma confirmação ausente ou uma duplicada. Para operações financeiras, essa decisão pode exigir uma reconciliação manual.
Eu começaria com três testes de integração. Primeiro, envie o mesmo evento duas vezes ao mesmo tempo e confirme uma linha na caixa de entrada e uma tarefa publicada para consumo. Depois, interrompa o servidor após o commit e antes da resposta. A próxima entrega deve encontrar o registro existente. Por fim, interrompa o consumidor após gravar a matrícula e antes de concluir a tarefa. Quando o trabalho voltar, a contagem de matrículas deve continuar em um. Esses testes observam o efeito persistido, que é o que interessa para quem usa o sistema.
Em produção, eu acompanharia a idade da tarefa pendente mais antiga e a contagem de repetições por origem. Uma alta de duplicidades com tarefas fluindo pode indicar reentregas do emissor. Uma fila com idade crescente pede investigação no consumidor. Defina ainda uma janela de retenção compatível com o prazo de reenvio do provedor e teste um replay fora dela. No seu sistema, qual dos efeitos de um webhook pode ser repetido sem consequência e qual precisa de uma chave própria desde o primeiro dia?
A idade da tarefa mais antiga ajuda muito. Eu também mediria o tempo entre o evento registrado e o primeiro processamento, porque a profundidade da fila pode parecer baixa mesmo com um consumidor travado em uma tarefa.
Eu adicionaria um teste para o mesmo identificador em duas contas. É fácil perder esse detalhe quando todos os testes usam o mesmo cliente de exemplo.
Boa. Também vale cobrir o identificador repetido na mesma conta com outro conteúdo. Eu registraria a divergência sem deixar a segunda carga sobrescrever a primeira.