Webhooks Kommo: evite duplicar tarefas e ações na integração

Um evento pode chegar mais de uma vez

O webhook avisa sua aplicação sobre uma mudança no CRM. Sua aplicação decide o que fazer. Se cada recebimento criar uma nova tarefa sem verificar o que já aconteceu, uma repetição pode duplicar a ação. Por isso, projete o consumidor para reconhecer eventos já tratados. Este guia apresenta um desenho de integração; não é uma configuração automática nem uma garantia de entrega da plataforma.

Receba primeiro, processe depois

Valide o formato, identifique a conta e registre o evento numa fila ou armazenamento confiável. Responda rapidamente ao recebimento e execute o trabalho mais demorado em outro passo. A documentação distingue webhooks gerais e do pipeline digital, com comportamentos de repetição diferentes. Consulte o tipo que você está usando; não aplique o mesmo pressuposto a todos os eventos.

Escolha uma chave de idempotência

Uma chave pode combinar conta, entidade, ação e um identificador ou versão do evento disponível no payload. Não use apenas o ID do lead: isso bloquearia futuras mudanças legítimas no mesmo lead. Quando não houver identificador único, defina uma estratégia explícita de comparação e janela temporal, sabendo quais eventos ela pode reunir incorretamente. Grave a chave e a ação de forma consistente para evitar corrida entre dois processadores.

Teste quatro situações antes de ativar

Envie o mesmo evento duas vezes: a ação externa deve ocorrer uma vez. Envie uma alteração posterior do mesmo lead: ela precisa ser reconhecida como nova. Simule indisponibilidade do serviço de destino: a falha deve ficar registrada para tratamento. Inverta a ordem de dois eventos: uma informação antiga não deve sobrescrever a atual sem uma regra. Teste com dados fictícios e não exponha tokens em logs.

Monitore o resultado, não só o recebimento

Uma resposta HTTP bem-sucedida informa que a chamada foi aceita, mas não prova que todo o trabalho posterior terminou. Registre os estados recebido, processado e falhou, com identificadores úteis para investigação. Se precisar consultar o CRM, respeite os limites da API e use espera progressiva após respostas de limite. Ofereça uma rotina de reprocessamento que preserve a mesma proteção contra duplicidade.

Fontes e próximos passos

As sugestões de desenho e os cenários de teste são exercícios editoriais da Metrik. Para recursos, disponibilidade e configuração atual, consulte a documentação da plataforma:

Continue com estes guias:

Construa o próximo projeto com a comunidade.

Veja as formações, os materiais e as monitorias da Kommo Academy.