Come funziona la consegna dei webhook
Shopify attiva un evento ORDERS_PAID nel momento in cui il pagamento viene catturato. L'evento atterra in un topic Google Cloud Pub/Sub, il worker di Alva preleva il messaggio, scrive le righe Customer e Purchase in PostgreSQL, poi invia l'email di consegna tramite Postmark o MailerToGo. Il buffer Pub/Sub è ciò che rende affidabile tutto questo: se un deploy è in corso o il database è momentaneamente lento, il messaggio aspetta in coda e viene riconsegnato finché il worker non riconosce il successo.
Diagramma di pipeline orizzontale semplice con cinque stadi etichettati: Shopify ORDERS_PAID → topic Google Cloud Pub/Sub → worker Alva → PostgreSQL (Customer + Purchase) → invio email (Postmark / MailerToGo). Usa il teal/blu del brand Alva. Nessun dato cliente reale.
Motivi comuni di ritardo
Carico pesante sulla coda Pub/Sub
Durante le flash sale il topic può contenere migliaia di messaggi pendenti. Il worker di Alva li scarica in ordine, quindi un ordine in fondo a una coda da 5.000 messaggi aspetta il suo turno. La latenza qui è di solito sotto i due minuti.
Controllo antifrode che trattiene l'email
Quando i controlli antifrode sono abilitati, il worker scrive l'ordine in FraudCheckQueue e mette in pausa la consegna finché l'API di rischio Shopify non risponde. La maggior parte dei controlli si risolve in secondi; gli ordini instradati a revisione manuale aspettano finché non li approvi. Le chiavi di licenza non sono mai assegnate prima dell'approvazione antifrode.
Rigenerazione di pack ZIP grandi
Se il prodotto è un pack e uno dei suoi file è cambiato dall'ultimo ZIP messo in cache, Alva rigenera l'archivio in R2 prima di inviare l'email. Pack di più gigabyte possono impiegare minuti.
Impostazione email per prodotto cambiata in volo
Se attivi un template email per prodotto o disabiliti le email per un prodotto mentre un ordine è in volo, il worker rilegge ProductEmailSettings al prossimo tentativo. L'ordine viene comunque completato — l'email semplicemente usa la nuova regola.
Retry del webhook da Shopify
Shopify ritenta un webhook fallito fino a 19 volte in circa 48 ore, con backoff tra i tentativi. Se la prima consegna ha colpito Alva durante un deploy, l'ordine potrebbe non apparire finché il prossimo retry non ha successo — di solito entro 5–10 minuti.
Cosa fare se sono passati più di 5 minuti
Cinque minuti coprono la grande maggioranza dei casi. Oltre quella finestra, segui questa checklist:
- Conferma che l'ordine sia pagato in Shopify — gli ordini in attesa o autorizzati non attivano mai
ORDERS_PAID. - Apri la lista ordini admin Alva. Trattenuto significa che l'antifrode sta gestendo la consegna; In elaborazione significa che il worker ci sta ancora lavorando.
- Controlla Impostazioni → Email per confermare che la consegna email sia abilitata e un mittente verificato sia configurato.
- Se l'ordine manca del tutto, ricorri a Trova il link di download di un cliente per riattivare la consegna manualmente.
Domande frequenti
Pub/Sub bufferizza i webhook durante deploy, interruzioni e picchi di traffico così un ordine pagato non viene mai perso. Il worker conferma il messaggio solo dopo che la riga Purchase è scritta.
No. La pagina di ringraziamento usa un token di download provvisorio dall'estensione checkout, così i file appaiono istantaneamente anche quando il webhook ORDERS_PAID è ancora in volo.
Fino a 19 volte in circa 48 ore, con backoff esponenziale. Finché Alva alla fine restituisce successo, l'ordine viene processato normalmente.
Vedi anche
È stato utile?
Ultimo aggiornamento 2026-05-06