Shopify Next Generation Events: webhook granulari con GraphQL

Il problema dei webhook tradizionali di Shopify

Chiunque abbia costruito un'integrazione ERP o PIM su Shopify conosce il problema: ogni volta che un prodotto viene aggiornato, il webhook spara l'intero payload, anche se è cambiato solo un tag o una metafield irrilevante per il sistema ricevente.

Questo genera tre inefficienze concrete:

• Volume elevato di delivery non azionabili, che consumano risorse di rete e di elaborazione
• Over-fetching strutturale, con campi inutili trasportati a ogni evento
• Logiche di diff applicativo, necessarie per capire cosa è effettivamente cambiato rispetto allo stato precedente

I Next Generation Events, ora disponibili in developer preview sulla Shopify Admin GraphQL API, affrontano questi tre problemi in modo diretto.

Tre dimensioni di controllo granulare

Il nuovo sistema introduce controllo su tre livelli distinti: cosa scatena la delivery, cosa contiene il payload, e cosa è cambiato.

1. Field-level triggers

Con i Next Generation Events è possibile definire una subscription su un percorso specifico come product.variants.price. Una subscription configurata in questo modo non scatta per modifiche al titolo, ai tag o ad altri campi: si attiva esclusivamente quando cambia il prezzo delle varianti.

Questo elimina alla radice la categoria delle delivery spurie, senza richiedere filtri lato applicazione.

2. Payload personalizzato via query GraphQL

Anziché ricevere un payload fisso determinato da Shopify, con il nuovo sistema si definisce direttamente la query GraphQL che popola ogni delivery. Il risultato è che ogni evento contiene esattamente i campi necessari per l'elaborazione, senza campi superflui e senza la necessità di una chiamata API aggiuntiva per recuperare i dati mancanti.

Per le integrazioni che oggi seguono il pattern webhook + API call di arricchimento, questo rappresenta una riduzione netta del numero di richieste verso l'API di Shopify.

3. Il campo fields_changed

Ogni delivery include ora un campo fields_changed con la lista esplicita dei percorsi modificati, comprensivi di path completo e ID entità. Questo rende obsoleta qualsiasi logica di confronto con lo stato precedente nel codice applicativo.

Invece di mantenere uno snapshot locale dell'entità e calcolare il diff a ogni evento, il sistema ricevente può leggere direttamente quali campi sono cambiati e agire di conseguenza.

query_filter: ridurre le delivery non azionabili

Un ulteriore meccanismo di controllo è il query_filter, che permette di filtrare le delivery in base allo stato corrente dell'entità al momento dell'evento. Un esempio tipico: consegnare eventi solo per prodotti con status ACTIVE, ignorando bozze e prodotti archiviati.

Combinato con i field-level triggers, il query_filter consente di costruire subscription molto precise, riducendo il traffico verso gli endpoint di ricezione a una frazione di quello attuale.

Config as code con shopify.app.toml

Le subscription Next Generation Events si configurano direttamente nel file shopify.app.toml, insieme al resto della configurazione dell'applicazione. Questo significa che la definizione degli eventi è:

• Versionabile nel repository del progetto
• Reviewabile nel processo di code review
• Riproducibile in ambienti diversi senza configurazioni manuali

Per team che gestiscono più ambienti (sviluppo, staging, produzione) o che seguono pratiche GitOps, questo approccio elimina la dipendenza da configurazioni gestite manualmente nella dashboard di Shopify.

Impatto pratico per integrazioni ERP e PIM

Per cataloghi ad alto volume, la somma di questi cambiamenti ha un impatto misurabile su performance e costi:

• Riduzione del numero di delivery ricevute grazie a trigger precisi e query_filter
• Riduzione della dimensione media dei payload grazie alle query GraphQL personalizzate
• Eliminazione delle chiamate API di arricchimento post-delivery
• Semplificazione del codice applicativo grazie a fields_changed

Le integrazioni che oggi processano migliaia di eventi al giorno con un basso tasso di azionabilità sono quelle che beneficiano maggiormente di questa architettura.

Raccomandazioni per chi inizia oggi

Il sistema è attualmente in developer preview sull'API unstable di Shopify, con supporto per le topic Product e Customer. Prima di valutarne l'adozione:

• Verifica il tuo traffico attuale: identifica i webhook con alto volume e bassa utilità del payload, sono i candidati prioritari alla migrazione
• Testa in preview: utilizza le topic Product e Customer disponibili oggi per validare il comportamento atteso
• Sostituisci le logiche di diff: refactoring guidato da fields_changed sui consumer esistenti
• Configura query_filter: definisci i criteri di filtraggio sullo stato corrente per eliminare delivery non azionabili
• Pianifica la migrazione: l'API è su unstable e non è adatta alla produzione senza un piano di migrazione verso una versione stabile

Se stai costruendo o evolvendo integrazioni custom su Shopify Plus e vuoi valutare l'architettura più adatta al tuo volume e ai tuoi requisiti, puoi trovare informazioni sui nostri servizi di sviluppo nella pagina dedicata agli sviluppatori Shopify.

Conclusione

I Next Generation Events non sono solo un miglioramento delle performance dei webhook: ridefiniscono il modello di integrazione con Shopify, spostando il controllo granulare sul lato dello sviluppatore. Per chi costruisce integrazioni serie su cataloghi ad alto volume, vale la pena esplorare questo pattern ora, prima che raggiunga la stabilità e diventi lo standard atteso.