Shopify Next Generation Events: webhook granulari cu GraphQL

Problema webhook-urilor tradiționale Shopify

Oricine a construit o integrare ERP sau PIM pe Shopify cunoaște problema: de fiecare dată când un produs este actualizat, webhook-ul trimite întregul payload, chiar dacă s-a schimbat doar un tag sau un metafield irelevant pentru sistemul receptor.

Acest lucru generează trei ineficiențe concrete:

• Volum ridicat de livrări neacționabile, care consumă resurse de rețea și de procesare
• Over-fetching structural, cu câmpuri inutile transportate la fiecare eveniment
• Logici de diff aplicativ, necesare pentru a înțelege ce s-a schimbat efectiv față de starea anterioară

Next Generation Events, disponibile acum în developer preview pe Shopify Admin GraphQL API, abordează direct aceste trei probleme.

Trei dimensiuni de control granular

Noul sistem introduce control pe trei niveluri distincte: ce declanșează livrarea, ce conține payload-ul și ce s-a modificat.

1. Triggere la nivel de câmp

Cu Next Generation Events este posibil să definești o subscription pe un traseu specific precum product.variants.price. O subscription configurată astfel nu se declanșează pentru modificări ale titlului, tag-urilor sau altor câmpuri: se activează exclusiv când se schimbă prețul variantelor.

Aceasta elimină din rădăcină categoria livrărilor parazite, fără a necesita filtre pe partea de aplicație.

2. Payload personalizat via query GraphQL

În loc să primești un payload fix determinat de Shopify, cu noul sistem definești direct query-ul GraphQL care populează fiecare livrare. Rezultatul este că fiecare eveniment conține exact câmpurile necesare procesării, fără câmpuri superflue și fără a fi nevoie de un apel API suplimentar pentru a recupera datele lipsă.

Pentru integrările care urmează astăzi pattern-ul webhook + API call de îmbogățire, aceasta reprezintă o reducere netă a numărului de cereri către API-ul Shopify.

3. Câmpul fields_changed

Fiecare livrare include acum un câmp fields_changed cu lista explicită a traseelor modificate, inclusiv path complet și ID-ul entității. Aceasta face obsoletă orice logică de comparare cu starea anterioară din codul aplicativ.

În loc să menții un snapshot local al entității și să calculezi diff-ul la fiecare eveniment, sistemul receptor poate citi direct ce câmpuri s-au schimbat și poate acționa în consecință.

query_filter: reducerea livrărilor neacționabile

Un mecanism suplimentar de control este query_filter, care permite filtrarea livrărilor în funcție de starea curentă a entității la momentul evenimentului. Un exemplu tipic: livrarea evenimentelor doar pentru produse cu statusul ACTIVE, ignorând schițele și produsele arhivate.

Combinat cu triggerele la nivel de câmp, query_filter permite construirea unor subscription-uri foarte precise, reducând traficul către endpoint-urile de recepție la o fracțiune din cel actual.

Config as code cu shopify.app.toml

Subscription-urile Next Generation Events se configurează direct în fișierul shopify.app.toml, împreună cu restul configurației aplicației. Aceasta înseamnă că definiția evenimentelor este:

• Versionabilă în repository-ul proiectului
• Reviewabilă în procesul de code review
• Reproductibilă în medii diferite fără configurații manuale

Pentru echipele care gestionează mai multe medii (dezvoltare, staging, producție) sau care urmează practici GitOps, această abordare elimină dependența de configurații gestionate manual în dashboard-ul Shopify.

Impact practic pentru integrări ERP și PIM

Pentru cataloage cu volum mare, suma acestor schimbări are un impact măsurabil asupra performanței și costurilor:

• Reducerea numărului de livrări primite datorită triggerelor precise și query_filter
• Reducerea dimensiunii medii a payload-urilor datorită query-urilor GraphQL personalizate
• Eliminarea apelurilor API de îmbogățire post-livrare
• Simplificarea codului aplicativ datorită fields_changed

Integrările care astăzi procesează mii de evenimente pe zi cu o rată scăzută de acționabilitate sunt cele care beneficiază cel mai mult de această arhitectură.

Recomandări pentru cei care încep astăzi

Sistemul se află în prezent în developer preview pe API-ul unstable al Shopify, cu suport pentru topic-urile Product și Customer. Înainte de a evalua adoptarea:

• Verifică traficul tău actual: identifică webhook-urile cu volum mare și utilitate scăzută a payload-ului — acestea sunt candidații prioritari pentru migrare
• Testează în preview: folosește topic-urile Product și Customer disponibile astăzi pentru a valida comportamentul așteptat
• Înlocuiește logicile de diff: refactoring ghidat de fields_changed pe consumerii existenți
• Configurează query_filter: definește criteriile de filtrare pe starea curentă pentru a elimina livrările neacționabile
• Planifică migrarea: API-ul este pe unstable și nu este adecvat pentru producție fără un plan de migrare către o versiune stabilă

Dacă construiești sau evoluezi integrări custom pe Shopify Plus și vrei să evaluezi arhitectura potrivită pentru volumul și cerințele tale, găsești informații despre serviciile noastre de dezvoltare pe pagina dedicată dezvoltatorilor Shopify.

Concluzie

Next Generation Events nu sunt doar o îmbunătățire a performanței webhook-urilor: redefinesc modelul de integrare cu Shopify, mutând controlul granular pe partea dezvoltatorului. Pentru cei care construiesc integrări serioase pe cataloage cu volum mare, merită explorat acest pattern acum, înainte ca acesta să atingă stabilitatea și să devină standardul așteptat.