Como receber webhooks sem duplicar ações em fluxos de arquivos

O problema: uma entrega nem sempre equivale a um evento

Em um fluxo real de arquivos, um webhook pode chegar mais de uma vez, chegar tarde ou aparecer em uma ordem diferente da esperada. Isso não é necessariamente um erro de projeto: as novas tentativas existem para superar interrupções de rede, quedas temporárias do receptor ou respostas HTTP ambíguas. O problema aparece quando o endpoint trata cada entrega como uma nova ação e volta a baixar um arquivo, convertê-lo, criar um ticket, enviar uma notificação ou registrar uma operação no ERP.

A primeira decisão arquitetônica é separar evento, entrega e efeito secundário. O evento representa algo que ocorreu na origem; a entrega é uma tentativa de comunicá-lo; o efeito secundário é o que seu sistema faz como consequência. Um receptor robusto não pergunta “já recebi esta solicitação antes?”, mas sim “este evento já foi aceito e que efeitos autorizados ele ainda pode produzir?”. Essa distinção é a base dos webhooks idempotentes.

• Risco típico: criar dois registros internos para o mesmo arquivo transformado.
• Risco típico: enviar várias notificações a clientes por uma única ação Cloud.
• Risco típico: sobrescrever uma versão nova com uma resposta tardia de um evento anterior.

O que seu receptor deve garantir antes de processar

Um receptor de webhooks deve garantir quatro coisas: autenticidade, rastreabilidade, idempotência e uma resposta HTTP previsível. Autenticidade significa comprovar que a mensagem vem da origem esperada e não foi modificada durante o transporte. Rastreabilidade significa conservar identificadores, data de entrega, estado interno e resultado. Idempotência significa que uma repetição do mesmo evento não duplica efeitos. A resposta HTTP indica à origem se a entrega foi aceita ou deve ser tratada como falha.

A regra operacional é rígida: primeiro verificar, depois aceitar de forma durável e só então responder corretamente. Se a transformação, o download ou a sincronização com o CRM puder demorar, não a execute dentro da janela crítica do webhook. Registre o evento em uma tabela ou fila transacional, marque seu estado inicial e delegue o trabalho pesado a um processo em segundo plano. Para casos assíncronos, 202 Accepted é uma resposta adequada quando a solicitação foi recebida, mas outro processo a gerenciará depois.

• Comprovar a assinatura antes de ler ou salvar o payload como dado confiável.
• Persistir a aceitação do evento antes de responder com sucesso.
• Não executar trabalhos longos na thread principal do endpoint.
• Usar estados internos visíveis para suporte e operações.

Assinatura HMAC: não confie no payload sem validá-lo

A assinatura é o primeiro filtro. Na Apification, as assinaturas HMAC são documentadas como mecanismo para verificar a procedência e a integridade do payload. A recomendação operacional é validar a assinatura HMAC antes de ler ou salvar o conteúdo como se fosse confiável. Se a validação falhar, o receptor não deve processar o evento, não deve disparar downloads e não deve iniciar trabalhos internos. Uma falha de assinatura não é um problema de negócio; é uma rejeição de segurança.

Uma verificação robusta não deveria depender apenas do corpo. Em especificações técnicas de webhooks, recomenda-se que a assinatura cubra o identificador, o timestamp e o body, porque o timestamp ajuda a reduzir ataques de repetição e pode diferir da data original do evento quando há novas tentativas. Na prática, sua implementação deve reconstruir exatamente a mensagem assinada segundo a documentação da origem, comparar a assinatura de forma segura e registrar apenas os metadados necessários para diagnóstico, nunca segredos.

• Rejeitar eventos com assinatura ausente, malformada ou não coincidente.
• Validar o timestamp de entrega segundo uma tolerância definida pela sua equipe.
• Não incluir segredos, tokens nem assinaturas completas em logs compartilhados.
• Manter separados os segredos de webhook por ambiente e destino.

Deduplicação prática com estados persistentes

Para deduplicar, você precisa de uma chave estável. Uma especificação de webhooks contempla um identificador único associado ao evento que permanece igual mesmo que uma entrega com falha seja tentada novamente. Esse identificador pode ser usado como chave de idempotência para que o consumidor processe um evento uma única vez, mesmo que ele seja recebido por problemas de rede, por erro ou de forma maliciosa. Se sua origem também fornecer um identificador de entrega, conserve-o para auditoria, mas não o use como única chave de evento.

O padrão mínimo é uma tabela de eventos com chave única, estado e resultado. Ao receber um webhook válido, tente inserir o event_id. Se ele já existir e estiver processado, responda corretamente sem repetir efeitos. Se existir em processamento, responda de forma coerente e evite iniciar outro worker. Se estiver em erro, decida se é permitido reenfileirá-lo manualmente ou após uma política interna. Essa abordagem transforma a duplicação de entregas em uma consulta de estado, não em uma repetição de trabalho.

• Campos recomendados: event_id, delivery_id se existir, tipo, recurso, data, estado, tentativas internas e último erro.
• Estados úteis: recebido, processando, processado, erro, descartado.
• Restrição-chave: índice único sobre o identificador estável do evento.
• Regra de suporte: toda ação manual deve deixar rastro de quem tentou novamente e quando.

Idempotência aplicada a ações sobre arquivos

Os arquivos adicionam riscos específicos. Uma mesma notificação pode acabar baixando duas vezes o mesmo recurso, gerando duas conversões ou notificando duas URLs distintas para um resultado equivalente. Projete cada etapa com uma operação de “criar se não existir” ou “avançar apenas se o estado permitir”. Por exemplo, crie o registro interno do arquivo uma única vez, associe a versão ou o identificador estável do recurso e salve o resultado da transformação como um artefato referenciado, não como uma escrita cega sobre o último valor disponível.

Também convém separar download, transformação e notificação. O download obtém a entrada e confirma que ela corresponde ao evento aceito. A transformação produz uma saída controlada, idealmente com um registro de trabalho. A notificação ao CRM, ERP ou gestor documental é realizada no final e apenas se as etapas anteriores chegaram ao estado esperado. Se chegar um evento tardio, compare-o com datas, estado e identificadores estáveis antes de modificar uma versão ou informar um resultado.

• Não sobrescrever versões sem verificar o estado atual do recurso interno.
• Não enviar notificações externas até que o resultado esteja persistido.
• Salvar o vínculo entre arquivo, projeto Cloud, evento e resultado interno.
• Tratar as transformações como trabalhos rastreáveis, não como respostas imediatas do endpoint.

Novas tentativas: quando aceitar, quando falhar e quando pausar

As novas tentativas são uma ferramenta, mas também amplificam defeitos se o receptor não for idempotente. A Apification documenta novas tentativas automáticas e manuais para falhas temporárias de webhooks. Por isso, seu endpoint deve distinguir entre “não posso aceitar o evento” e “já o aceitei, mas vou processá-lo depois”. Se a assinatura for válida e você puder salvar o evento de forma durável, responda com sucesso ou com 202 Accepted e deixe sua fila interna gerenciar o trabalho. Assim você evita que uma conversão lenta provoque entregas repetidas desnecessárias.

Se seu banco de dados, fila ou armazenamento de eventos não estiver disponível, não finja aceitação. Em condições temporárias do servidor, 503 Service Unavailable é o código adequado e pode ser acompanhado de Retry-After quando você tiver uma estimativa. Os erros 4xx devem ser reservados para problemas atribuíveis à solicitação, como formato inválido ou assinatura rejeitada. A consistência dessas respostas facilita interpretar o histórico de entregas e evita misturar incidentes de segurança com saturação operacional.

• Aceitar apenas quando o evento ficou persistido ou enfileirado de forma durável.
• Devolver erro se você não puder registrar o evento e precisar que a origem tente novamente.
• Não usar novas tentativas externas para compensar processos internos mal projetados.
• Revisar eventos em erro antes de tentar novamente manualmente para não duplicar efeitos.

Como a Apification se encaixa em uma arquitetura segura

A Apification permite integrar Cloud e seus serviços por meio de API REST, OpenAPI, webhooks, iframe e JavaScript. Para integrações servidor a servidor, a API REST permite gerenciar recursos Cloud, usuários, configuração e trabalhos de transformação a partir do backend. Em fluxos orientados a eventos, os webhooks assinados ajudam a reagir a mudanças sem consultar continuamente recursos ou trabalhos em segundo plano. A Apification documenta eventos relacionados a arquivos, serviços, formulários, assinaturas e processos.

A parte operacional também importa. A Apification documenta histórico de entregas de webhook com URL de destino, data, estado e corpo de resposta, além de estatísticas e novas tentativas automáticas e manuais. Também documenta comandos idempotentes por meio de uma chave estável em escritas para que as novas tentativas de rede não repitam a ação. Em projetos com arquivos grandes, os trabalhos assíncronos permitem importar e transformar recursos em segundo plano, conservando progresso e erros detalhados.

• Usar OpenAPI 3.1 baixável como contrato para esquemas de solicitação e resposta.
• Combinar REST API para ações iniciadas pelo seu backend e webhooks para mudanças relevantes.
• Consultar histórico e estatísticas para depurar falhas de entrega sem depender apenas de logs internos.
• Aplicar chaves idempotentes em escritas quando uma operação puder ser tentada novamente.

Exemplo de implementação operacional

Uma arquitetura razoável é: webhook da Apification, endpoint verificador, tabela ou fila de eventos, worker, API interna ou CRM e registro final por arquivo ou projeto Cloud. O endpoint valida a assinatura HMAC, verifica timestamp e estrutura, extrai o identificador estável do evento, tenta inseri-lo com uma restrição única e responde quando a aceitação está persistida. O worker pega eventos no estado recebido, marca-os como processando, executa o download ou a consulta necessária por meio de APIs, inicia transformações se for o caso e registra o resultado.

As falhas esperadas devem estar definidas antes da produção. Se a assinatura falhar, o evento é rejeitado e não é processado. Se o evento já existir, devolve-se uma resposta correta sem repetir o trabalho. Se o CRM estiver fora do ar, o worker conserva o evento em erro ou pendente conforme sua política interna. Se chegar um evento antigo, ele é comparado contra estado, datas e identificadores antes de modificar qualquer coisa. Nenhum segredo deve aparecer em logs, parâmetros de URLs públicas ou mensagens de erro visíveis.

• Checklist prévio: assinatura validada, chave única criada, estados definidos e logs sem segredos.
• Checklist de testes: entrega duplicada, entrega tardia, assinatura inválida, queda do banco de dados e queda do CRM.
• Checklist de operação: revisar histórico de entregas, eventos em erro, novas tentativas manuais e tempos de fila.
• Critério de saída: cada arquivo tem um único resultado destacado ou um erro explicável e rastreável.

Perguntas frequentes