Proteção contra entregas duplicadas
A maioria dos sistemas tenta novamente enviar um webhook quando não recebe uma resposta rápida. Se a primeira tentativa tiver sido efetivamente recebida, seu fluxo de trabalho do Shopify Flow será executado duas vezes para um único evento - um segundo e-mail, uma etiqueta duplicada, uma nota de pedido repetida.
A proteção contra entregas duplicadas impede que isso aconteça. Ela vem desativada por padrão em todos os webhooks.
Como funciona
Caso seu sistema de envio inclua um identificador exclusivo para cada evento, defina o nome do cabeçalho que o contém em Configurações avançadas -> Detecção de entrega duplicada.
| Comportamento | |
|---|---|
| Primeira solicitação com um determinado ID | Quando processados normalmente, os incêndios se propagam |
| Repita dentro de 24 horas | 200 OK com duplicate: true - não enviado para o Shopify Flow |
| Um ID diferente | Processado normalmente |
| Solicite sem esse cabeçalho | Processado normalmente |
| Campo deixado em branco | Cada solicitação processada - nada muda |
Nomes comuns de cabeçalhos: Event-Id, Idempotency-Key, X-Request-Id. A correspondência não diferencia 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 a repetição ainda retorna 200?
Uma resposta que não seja do código 2xx é exatamente o que dificulta a tentativa de repetição por parte do remetente. Responder com 200 indica que o evento foi tratado com segurança, de modo que o processo é interrompido - enquanto duplicate: true no corpo da resposta permite distinguir os dois resultados caso você registre as respostas.
Onde aparecem as duplicatas
Uma duplicata suprimida:
- não cria nenhuma entrada no histórico de chamadas, portanto, não é contabilizado no seu plano
- aparece no Live Request Inspector enquanto o senhor estiver editando o webhook, marcada como uma duplicata suprimida
Essa combinação é intencional: seu histórico e sua cota permanecem intactos, mas nunca parece que uma chamada tenha desaparecido sem deixar vestígios.
Escolhendo o cabeçalho adequado
O identificador deve permanecer **estável ao longo da tentativa de repetição e **ser único para cada evento - esse é todo o mecanismo.
Correto: um ID de evento ou uma chave de idempotência gerada uma única vez pelo remetente no momento em que o evento ocorre.
Inadequado e rejeitado no momento do salvamento: cabeçalhos controlados por proxy, como X-Forwarded-For, CF-* ou X-Signature. Seu valor muda a cada solicitação ou a cada salto, portanto, nunca corresponderiam a uma repetição - resultando em uma falha silenciosa, em vez de uma falha evidente.
Caso o repositório de deduplicação fique indisponível por um breve período
A entrega é processada em vez de ser descartada. A execução duplicada de um fluxo de trabalho representa um problema muito menor do que a perda de um evento; portanto, o recurso foi projetado para operar na modalidade “fail-open”.