Shopify Events: cambia la struttura dei payload

Shopify Events cambia struttura: cosa sta succedendo

Shopify Events non è un webhook classico. È un sistema più granulare, pensato per notificare variazioni specifiche sulle risorse dello store, e da oggi la sua struttura cambia in modo sostanziale. Se la tua app o integrazione legge i payload degli Events, l'aggiornamento del codice non è opzionale: senza intervento, il rischio di rottura è concreto.

Questo cambiamento riguarda in particolare chi ha costruito logiche custom su middleware, sistemi ERP o pipeline di sincronizzazione dati basate su Events API.

Le modifiche concrete al payload

Le novità introdotte da Shopify toccano sia la struttura dei dati sia la configurazione delle subscription.

fields_changed diventa un oggetto strutturato

Fino a oggi, fields_changed era un array piatto che elencava i campi modificati senza distinguere il tipo di variazione. Da ora diventa un oggetto con tre array distinti:

• added, per i campi aggiunti
• updated, per i campi modificati
• removed, per i campi rimossi

Un esempio pratico: aggiungere una variante a un prodotto ora finisce in fields_changed.added, non più in un array generico indifferenziato. Questo significa che il payload stesso comunica il tipo di operazione avvenuta, senza ambiguità.

Trigger parent con wildcard esplicito

I trigger che fanno riferimento a una risorsa parent richiedono ora un wildcard esplicito. Un trigger come product.variants deve essere riscritto come product.variants.*. Questa modifica va riportata nel file di configurazione dell'app, shopify.app.toml, prima del prossimo deploy.

Header di delivery rimossi

Due header utilizzati finora per identificare eventi e risorse non sono più presenti nelle richieste di delivery:

• shopify-event-id
• shopify-resource-id

Qualsiasi logica che dipende da questi header per il parsing o la deduplicazione degli eventi va rivista.

Subscription con azione update

Le subscription che utilizzano l'azione update devono ora avere almeno un trigger definito. Configurazioni senza trigger espliciti non saranno più valide.

Perché questo cambiamento è rilevante

Il punto centrale di questo aggiornamento è un cambio di paradigma nel modo in cui le integrazioni interpretano gli eventi. Prima, per capire cosa fosse realmente cambiato su una risorsa, era spesso necessario interrogare nuovamente l'API e confrontare lo stato precedente con quello attuale. Ora il payload comunica direttamente la natura della modifica, riducendo chiamate API ridondanti e semplificando la logica di elaborazione lato middleware o ERP.

Si tratta quindi di un miglioramento strutturale, ma che richiede un intervento attivo da parte di chi gestisce integrazioni basate su Events API.

Cosa fare subito

Per chi sviluppa o mantiene app e integrazioni Shopify, questi sono i passaggi da affrontare prima del prossimo deploy:

• Aggiornare la logica che legge fields_changed per usare .added, .updated e .removed invece dell'array piatto precedente
• Rimuovere qualsiasi dipendenza dagli header shopify-event-id e shopify-resource-id
• Aggiornare shopify.app.toml con la sintassi wildcard sui trigger parent
• Aggiornare i pacchetti Shopify API all'ultima versione disponibile

Classic Webhook non sono coinvolti

È importante chiarire che le Classic Webhook subscription non sono interessate da questo cambiamento: continuano a funzionare come prima. Il problema riguarda esclusivamente chi utilizza Events API, specialmente con logiche custom su middleware o sistemi di integrazione con ERP esterni.

Se la tua azienda gestisce integrazioni Shopify complesse, vale la pena pianificare un audit del codice che consuma Events prima del prossimo deploy, per evitare interruzioni impreviste su flussi di sincronizzazione dati critici.

Un cambiamento da monitorare nel tempo

Aggiornamenti come questo confermano quanto sia importante mantenere le integrazioni allineate alle evoluzioni della piattaforma Shopify, specialmente quando si lavora con logiche di automazione avanzate. Per chi gestisce progetti di sviluppo custom su Shopify, affidarsi a competenze tecniche specializzate permette di anticipare questi cambiamenti invece di subirli. Chi desidera approfondire i costi e le modalità di collaborazione con un team di sviluppo Shopify può consultare la pagina prezzi per sviluppatori Shopify per valutare un audit o un intervento di aggiornamento mirato.

Monitorare i changelog ufficiali di Shopify resta comunque la pratica più efficace per non farsi cogliere di sorpresa da modifiche strutturali come questa.