Protezione contro le consegne duplicate
La maggior parte dei sistemi riprova a inviare un webhook quando non riceve una risposta immediata. Se il primo tentativo è effettivamente andato a buon fine, il workflow di Shopify Flow viene eseguito due volte per un unico evento: una seconda e-mail, un tag duplicato, una nota d’ordine ripetuta.
La protezione contro le consegne duplicate impedisce che ciò accada. Per impostazione predefinita, è disattivata su ogni webhook.
Come funziona
Se il Suo sistema di invio include un ID univoco per ogni evento, indichi il nome dell’intestazione che lo contiene nella sezione “Impostazioni avanzate” -> “Rilevamento delle consegne duplicate”.
| Comportamento | |
|---|---|
| Prima richiesta con un determinato ID | Se trattati normalmente, i fuochi scorrono |
| Ripetere entro 24 ore | 200 OK con duplicate: true - non inviato a Shopify Flow |
| Un ID diverso | Elaborato normalmente |
| Richiesta senza tale intestazione | Elaborato normalmente |
| Campo lasciato vuoto | Ogni richiesta viene elaborata - nulla cambia |
Nomi comuni delle intestazioni: Event-Id, Idempotency-Key, X-Request-Id. La corrispondenza non tiene conto delle maiuscole e delle minuscole.
# 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"}'Perché il comando "repeat" continua a restituire il codice 200
Una risposta diversa da 2xx è proprio ciò che rende più difficile per un mittente riprovare. Rispondere con 200 indica che l’evento è stato gestito in modo sicuro, quindi il mittente interrompe il tentativo, mentre l’inclusione di duplicate: true nel corpo della risposta consente di distinguere i due esiti nel caso in cui si registrino le risposte.
Dove compaiono i duplicati
Un duplicato nascosto:
- non crea alcuna voce nella cronologia delle chiamate, pertanto non viene conteggiata ai fini del Suo piano
- viene visualizzato nell'Inspector delle richieste in tempo reale mentre si sta modificando il webhook, contrassegnato come duplicato soppresso
Questa combinazione è voluta: la cronologia e la quota rimangono intatte, ma una chiamata non dà mai l’impressione di essere scomparsa senza lasciare traccia.
Scegliere l'intestazione giusta
L'ID deve rimanere invariato durante il tentativo di ripetizione ed essere univoco per ogni evento: questo è l'intero meccanismo.
Corretto: un ID evento o una chiave di idempotenza generata una sola volta dal mittente al verificarsi dell'evento.
Non valido e rifiutato al momento del salvataggio: intestazioni controllate da proxy quali X-Forwarded-For, CF-* o X-Signature. Il loro valore varia a ogni richiesta o a ogni hop, pertanto non corrisponderebbero mai a una ripetizione, generando un errore silenzioso anziché evidente.
Qualora l'archivio di deduplicazione risultasse temporaneamente non disponibile
La consegna viene elaborata anziché ignorata. L’esecuzione duplicata di un workflow rappresenta un problema di gran lunga minore rispetto alla perdita di un evento; pertanto, per impostazione predefinita, la funzionalità opera in modalità “fail-open”.