API e automatização

Webhooks fora de ordem: como evitar que um evento antigo reverta o estado de um ficheiro

A hora de receção não prova qual alteração ocorreu primeiro. Saiba como rever o contrato do webhook e reconciliar o estado do ficheiro com critérios verificáveis.

Apification
Diagrama de eventos de ficheiros que chegam em ordens diferentes e de uma aplicação que reconcilia o respetivo estado

A receção não prova a ordem das alterações

Um webhook pode avisar a sua aplicação sobre um evento assíncrono, mas a hora a que o seu servidor o recebe não prova quando ocorreu a alteração nem qual de duas alterações aconteceu primeiro. Por isso, se cada aviso substituir simplesmente o registo local, poderá acabar com uma vista desatualizada.

As referências gerais ajudam a compreender a utilização de webhooks, mas não estabelecem um contrato de ordenação para a sua integração: a Stripe apresenta-os como uma forma de responder a eventos assíncronos ([documentação da Stripe](https://docs.stripe.com/webhooks?locale=es-ES)); a Microsoft recomenda webhooks do Microsoft Graph para reagir a alterações de ficheiros no SharePoint Embedded ([Microsoft Learn](https://learn.microsoft.com/es-es/sharepoint/dev/embedded/build/respond-to-changes-webhooks)); e a Shopify descreve a sua utilização para obter e armazenar dados de um evento ([Shopify](https://help.shopify.com/es/manual/fulfillment/setup/notifications/webhooks)). Para decidir como ordenar ou reconciliar eventos, consulte a documentação técnica do fornecedor específico.

Os padrões de implementação deste artigo são recomendações gerais, não garantias de entrega, ordem ou consistência de uma plataforma. Separe a hora da alteração, a hora de emissão do evento e a hora de receção; utilize campos para comparar eventos apenas se o fornecedor documentar a respetiva semântica e âmbito.

  • Registe o significado de cada campo temporal e o âmbito em que pode ser comparado.
  • Utilize a hora de receção local para fins de observabilidade, não como prova de causalidade.
A receção não prova a ordem das alterações

Modele uma chegada fora de ordem

Imagine que «orçamento.docx» é renomeado para «orçamento-final.docx» e, em seguida, movido para uma pasta de aprovação. Se o aviso da movimentação chegar primeiro e o aviso da renomeação chegar depois, aplicar cada mensagem como verdade definitiva poderá repor uma localização ou um nome obsoletos. O facto de a entrega ser posterior não faz do evento a alteração mais recente.

Antes de implementar, desenhe o estado inicial, as alterações reais, os avisos emitidos, a ordem de receção e o resultado local esperado. Registe se cada aviso descreve uma alteração parcial ou inclui um estado completo; essa diferença influencia a forma como deve ser processado.

  • Teste o caso em que a alteração A ocorre antes da B, mas o aviso da A é processado depois.
  • Confirme que o registo local não recua devido à ordem de chegada.
Modele uma chegada fora de ordem

Verifique o contrato antes de comparar eventos

Procure na documentação um campo de sequência, versão ou tempo que o fornecedor defina expressamente como comparável. Confirme o seu significado e âmbito, o comportamento quando não existem valores e se o valor pode ser reiniciado. Um nome como «updated_at» ou «version» não basta, por si só, para estabelecer que dois avisos podem ser ordenados.

Se o fornecedor documentar uma sequência monotónica aplicável ao ficheiro, pode utilizá-la como critério de aceitação: guarde, juntamente com o estado local, o último valor aceite e compare cada aviso de acordo com as regras documentadas. Proteja a comparação e a escrita com uma operação atómica. Defina o que fazer com valores iguais, ausentes ou inválidos, em vez de os tratar automaticamente como recentes.

  • Documente o campo, a semântica, o âmbito de comparação e o tratamento de valores não comparáveis.
  • Uma atualização atómica protege o registo local contra escritas concorrentes; não prova que todos os eventos foram recebidos.

Sem um critério de ordenação fiável, considere uma leitura de reconciliação

Se não existir um campo de ordenação documentado, um possível padrão de conceção consiste em tratar o webhook como um aviso de que o ficheiro poderá ter sido alterado e consultar o recurso através da API, se o fornecedor disponibilizar essa operação. Verifique se consegue identificar o ficheiro e se a resposta inclui os campos necessários.

Uma resposta da API não garante, por si só, que está a ler o estado remoto mais recente: a documentação do fornecedor deve esclarecer as garantias de consistência e o efeito das caches, se existirem. Se essas garantias não estiverem documentadas, considere a leitura uma fonte de informação útil, não uma prova de atualidade.

Se a leitura falhar ou não permitir identificar o recurso, mantenha o estado local que já possui e aplique uma política de novas tentativas adequada ao seu sistema. Distinga um erro temporário de uma confirmação de que o ficheiro já não existe.

  • Verifique a operação de leitura, o identificador necessário, os campos devolvidos e as garantias de consistência documentadas.
  • Não transforme uma leitura falhada numa eliminação nem numa atualização confirmada.

Proteja a escrita local contra respostas concorrentes

Dois avisos podem iniciar leituras em simultâneo. Se a primeira demorar mais e a respetiva resposta for guardada depois da segunda, poderá substituir um resultado que já foi escrito. A ordem em que as consultas terminam não prova qual das respostas reflete dados remotos mais recentes.

Pode serializar as reconciliações por ficheiro ou atribuir a cada pedido uma geração local e verificá-la ao guardar. Essa geração ajuda a impedir que um trabalho local anterior substitua um posterior, mas não estabelece qual resposta contém dados remotos mais recentes. Para isso, continuam a ser necessárias as garantias documentadas da API. Outra opção é agrupar os avisos e consultar depois de uma sequência de notificações, se a latência resultante for aceitável.

  • Teste respostas da API que terminam por ordem inversa à ordem em que as consultas foram iniciadas.
  • Separe a proteção contra escritas locais obsoletas da garantia de atualidade dos dados remotos.

Teste repetições, permutações e falhas

Execute o mesmo conjunto de alterações com avisos pela ordem normal, pela ordem inversa e noutras permutações. Inclua avisos repetidos: a deduplicação é um problema relacionado, mas distinto da ordenação. Verifique o estado final esperado, não apenas o código de resposta do recetor.

Varie os casos: renomeação e movimentação, alteração da localização e do estado, duas renomeações seguidas e combinações de campos de avisos parciais. Inclua falhas de leitura da API e dois processos concorrentes. Se trabalhar com ficheiros com versões, pode comparar o registo local com o histórico disponível; não presuma que esse histórico substitui um contrato de ordenação.

  • Critério de aceitação: as permutações testadas não fazem o registo recuar relativamente ao estado verificado, de acordo com as garantias disponíveis.
  • Registe separadamente as falhas de entrega, leitura e atualização local.

Registe o necessário para diagnosticar discrepâncias

Registe uma referência segura ao ficheiro, o tipo de evento, os campos de ordenação documentados, se existirem, a hora de receção, o resultado da leitura da API e a decisão de escrita local. Um identificador de correlação próprio pode ajudar a acompanhar a notificação até à reconciliação. Evite guardar tokens, segredos ou o conteúdo completo do ficheiro e limite os dados pessoais ao estritamente necessário.

Mantenha o registo útil para determinar se o evento foi recebido, se foi possível consultar o recurso e por que motivo uma escrita foi aceite ou rejeitada. A Apification disponibiliza integração através de REST API e webhooks, e as suas funcionalidades de automatização incluem novas tentativas, histórico e estatísticas. Consulte a documentação aplicável para confirmar que informações estão disponíveis no seu fluxo; estas funcionalidades ajudam a observar uma integração, mas não estabelecem um critério de ordenação.

  • Separar a receção, a leitura, a comparação e a escrita facilita a identificação do ponto de divergência.
  • Não inclua credenciais nem segredos nos registos.

Perguntas frequentes

Posso ordenar os eventos pela hora a que o meu servidor os recebe?

Não como prova de qual alteração ocorreu primeiro. A receção pode sofrer atrasos; utilize um campo de ordenação apenas se o fornecedor documentar o seu significado e âmbito.

Uma leitura da API devolve sempre o estado mais recente?

Não necessariamente. Verifique na documentação as garantias de consistência e o possível efeito das caches. Sem essa informação, não trate uma resposta como prova de atualidade.

O que devo fazer se o webhook não incluir um campo de sequência?

Se a API disponibilizar uma leitura adequada e documentar como identificar o recurso, pode tratar o webhook como um aviso para iniciar uma reconciliação. Verifique também as garantias da leitura; se não houver uma opção adequada, consulte o contrato do fornecedor.

A Apification garante que os webhooks de ficheiros chegam por ordem?

A informação de produto disponível confirma a integração através de REST API e webhooks, além de novas tentativas, histórico e estatísticas para automatizações; não especifica uma garantia de ordenação para eventos de ficheiros. Consulte a documentação aplicável antes de depender dela.

Fontes e leituras

Documentação consultada para preparar este artigo.

Explore Apification

Artigos relacionados

Voltar ao blog