Redação: 4SYSTEMPublicado em Atualizado em

7 min de leitura

Como separar receção e processamento de negócio, resistir a duplicados e recuperar eventos após uma falha sem repetir as ações.

Para tornar fiáveis os webhooks no comércio eletrónico, verifique a assinatura, registe a entrega de forma duradoura antes de confirmar a receção e execute as ações com proteção contra duplicados. Um webhook é uma notificação enviada à sua aplicação; recebê-la não prova que a encomenda tenha sido processada. A Shopify documenta entregas repetidas e a Stripe esclarece que a ordem de chegada dos eventos não é garantida.[1][3] Conceba, por isso, o circuito para suportar repetição, atraso e interrupção.

Distinguir entrega, evento e ação de negócio

A entrega é o pedido recebido. O evento é aquilo que aconteceu na plataforma. A ação de negócio é o que o sistema decide fazer: atualizar um estado, criar uma tarefa de preparação ou transmitir um pedido. Estas identidades não são intercambiáveis. Na Shopify, a documentação distingue X-Shopify-Webhook-Id para deduplicar entregas de X-Shopify-Event-Id para correlacionar várias entregas provenientes da mesma ação do comerciante.[1]

Defina também qual é o sistema de referência para cada dado. Uma notificação antiga não deve substituir cegamente um estado mais recente. Conforme a necessidade, o processamento pode voltar a consultar o objeto atual na plataforma e decidir se a ação continua pertinente. Identificadores, âmbito da conta e versão do formato devem constar do contrato de integração. Esta precisão é mais útil do que uma promessa geral deautomação de marketing.

Atribuir uma responsabilidade a cada etapa

Uma arquitetura clara separa a receção rápida do pedido do trabalho que pode demorar. A Shopify recomenda uma fila para absorver picos; a Stripe também recomenda processamento assíncrono.[1][3] A grelha seguinte descreve responsabilidades de conceção, não uma garantia automaticamente fornecida por uma biblioteca.

Responsabilidades do circuito de receção
Etapa do webhookResponsabilidadeProva técnica a conservar
Receção de um webhookVerificar a origem e o formato esperadoResultado da validação e identificador
RegistoConservar uma tarefa duradoura e o seu estadoIdentificador da tarefa e data de receção
ProcessamentoAplicar uma ação sem efeitos repetidosChave de negócio e resultado da operação
Recuperação após um incidenteReexaminar tarefas incompletasHistórico de tentativas e motivo da falha

Separar a receção do processamento

A assinatura deve ser verificada sobre o corpo original, antes de qualquer transformação o modificar. A Shopify e a Stripe indicam-no nas respetivas documentações.[1][3] Utilize as ferramentas oficiais adequadas ao seu ambiente e mantenha os segredos fora dos registos. Uma assinatura válida não dispensa o controlo de duplicados nem as regras de negócio.

  1. Receber o pedido, preservar o corpo original e verificar a assinatura segundo o contrato exato do fornecedor. Rejeitar uma validação inválida sem iniciar uma ação de negócio.
  2. Construir uma identidade persistente que inclua o fornecedor, a conta em causa e o identificador de entrega ou evento adequado.
  3. Registar a tarefa com uma restrição de unicidade. Uma simples pesquisa seguida de uma inserção separada permite uma condição de corrida entre pedidos concorrentes.
  4. Confirmar a receção apenas depois desse registo duradouro. Se o armazenamento falhar, não declarar aceite uma tarefa que pode perder-se.
  5. Entregar o processamento a um executor separado, com estados explícitos, reserva do trabalho e proteção da ação de negócio contra repetições.
  6. Conservar o resultado e prever a recuperação de tarefas falhadas ou abandonadas, sem repetir indiscriminadamente todas as ações bem-sucedidas.

A deduplicação de uma entrega não basta se o processo falhar depois da ação externa, mas antes do registo local. Para esse caso, preveja uma chave de idempotência aceite pelo sistema destinatário ou uma verificação do efeito já produzido. Aqui, idempotência significa que uma repetição não cria um efeito de negócio adicional. Uma transação local, por si só, não consegue abranger uma ação remota independente.

Exemplo fictício: uma preparação criada uma única vez

Exemplo inteiramente fictício: um evento chamado evt-demo diz respeito à encomenda CMD-DEMO. A aplicação recebe uma entrega, guarda-a e cria uma tarefa de preparação. Chega outra entrega após uma interrupção de rede. O circuito reconhece a identidade já conservada e não cria uma nova tarefa de negócio. Pode confirmar a receção porque o trabalho inicial continua a ser acompanhado de forma duradoura, mesmo sem estar concluído.

Se a ferramenta logística tiver aceite a preparação antes de uma falha do executor, a recuperação verifica a chave de negócio associada a CMD-DEMO em vez de enviar uma nova criação sem controlo. Os estados devem distinguir «recebido», «em curso», «concluído» e «a recuperar». Este exemplo não afirma qualquer comportamento de uma aplicação real: cada sistema destinatário tem de ser avaliado quanto a esta proteção.

Preparar incidentes e reconciliação

As novas tentativas do fornecedor não substituem o seu procedimento de recuperação. A Shopify explica como voltar a importar dados em falta após uma indisponibilidade e verificar as subscrições em causa.[2] Defina uma janela de reconciliação, os dados a consultar, as autorizações de recuperação e o controlo final. Uma notificação de venda não deve tornar-se automaticamente prova de receita no seu plano de medição de eventos.

  • Prever um ensaio de entregas idênticas e concorrentes: espera-se uma única ação de negócio.
  • Prever uma interrupção após o armazenamento e outra após a ação externa para verificar ambos os percursos de recuperação.
  • Prever eventos atrasados ou fora de ordem e controlar se o estado final continua coerente com a origem.
  • Acompanhar a antiguidade das tarefas, as falhas e os resultados da reconciliação, limitando os registos aos dados necessários.

Perguntas frequentes

Uma resposta de sucesso significa que tudo terminou?

Não. Pode significar que a notificação foi aceite de forma duradoura para processamento. O estado de negócio deve ser acompanhado separadamente. Esta distinção permite uma receção rápida sem afirmar que a operação logística ou contabilística já foi concluída. Documente precisamente o compromisso que a resposta representa.

Pode utilizar-se o mesmo identificador em todo o lado?

Não sem verificar o seu âmbito. Um identificador pode designar uma entrega, um evento ou um objeto de negócio. A Shopify distingue, nomeadamente, os identificadores de entrega dos de correlação de eventos. A escolha depende do efeito a proteger e do perímetro da integração, não apenas do nome do cabeçalho.[1]

A fila garante um processamento exatamente uma vez?

Não o pressuponha. O circuito deve suportar a recuperação e proteger o efeito final, incluindo após uma falha entre sistemas. Verifique separadamente armazenamento, concorrência e idempotência do destinatário. Uma receção sem erros não demonstra esta propriedade de ponta a ponta.

Descrever as garantias antes de ligar as ferramentas

Webhooks fiáveis no comércio eletrónico exigem uma identidade clara, armazenamento duradouro e ações verificáveis após um incidente. Comece pelo cenário em que uma repetição seria dispendiosa e defina depois as provas de receção e sucesso. Para enquadrar as trocas entre loja e ferramentas de negócio, os serviços da 4SYSTEM permitem discutir o contrato de integração e a validação, sem apresentar um exemplo pedagógico como conector universal.

Fontes

  1. Verify webhook deliveries
  2. Troubleshoot webhooks
  3. Recevez les événements Stripe dans votre endpoint de webhook

PT