Proteção contra entregas duplicadas
A maioria dos sistemas volta a tentar enviar um webhook quando não obtém uma resposta rápida. Se a primeira tentativa tiver sido efetivamente recebida, o seu fluxo de trabalho Shopify Flow é executado duas vezes para um único evento - um segundo e-mail, uma etiqueta duplicada, uma nota de encomenda repetida.
A proteção contra entregas duplicadas impede que isso aconteça. Esta funcionalidade está desativada por predefinição em todos os webhooks.
Como funciona
Se o seu sistema de envio incluir um identificador único por evento, indique o nome do cabeçalho que o contém em «Definições avançadas» → «Detecção de entregas duplicadas».
| Comportamento | |
|---|---|
| Primeira solicitação com um determinado ID | Quando processados normalmente, os incêndios propagam-se |
| Repita no prazo de 24 horas | 200 OK com duplicate: true - não enviado para o Shopify Flow |
| Um identificador diferente | Processado normalmente |
| Envie o pedido sem esse cabeçalho | Processado normalmente |
| Campo deixado em branco | Todas as solicitações são processadas - nada muda |
Nomes comuns de cabeçalhos: Event-Id, Idempotency-Key, X-Request-Id. A correspondência não distingue maiúsculas de minúsculas.
# Same Event-Id twice - the second is accepted but not re-sent to Flow
curl -X POST https://your-app-url/webhook/ab12cd34 \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-token" \
-H "Event-Id: evt_12345" \
-d '{"orderId":"1001"}'Por que é que a repetição continua a devolver o valor 200?
Uma resposta que não seja do tipo 2xx é exatamente o que dificulta a repetição da tentativa por parte do remetente. Responder com 200 indica que o evento foi tratado com segurança, pelo que a tentativa é interrompida - enquanto que duplicate: true no corpo da resposta permite distinguir os dois resultados, caso registe as respostas.
Onde surgem as duplicatas
Uma duplicado suprimida:
- não cria qualquer registo no histórico de chamadas, pelo que não conta para o seu plano
- aparece no Live Request Inspector enquanto estiver a editar o webhook, classificada como uma duplicado suprimido
Essa combinação é intencional: o seu histórico e a sua cota permanecem intactos, mas uma chamada nunca dá a impressão de ter desaparecido silenciosamente.
Escolher o cabeçalho adequado
O identificador deve permanecer **estável ao longo da nova tentativa e **ser único para cada evento - é esse o mecanismo na sua totalidade.
Correto: um identificador de evento ou uma chave de idempotência gerada uma única vez pelo remetente quando o evento ocorre.
Inadequado e rejeitado no momento do armazenamento: cabeçalhos controlados por proxy, tais como X-Forwarded-For, CF-* ou X-Signature. O seu valor varia de pedido para pedido ou de salto para salto, pelo que nunca corresponderiam a uma repetição - falhando silenciosamente em vez de de forma evidente.
Caso o repositório de deduplicação fique temporariamente indisponível
A entrega é processada em vez de ser descartada. A execução duplicada de um fluxo de trabalho constitui um problema muito menor do que a perda de um evento, pelo que a funcionalidade foi concebida para dar prioridade à segurança.