Webhook Shopify: configurazione e debug

I webhook permettono di ricevere notifiche real-time da Shopify quando avvengono eventi: order/create, product/update, customer/create, ecc. Sono essenziali per integrazioni ERP, CRM, sync inventario e automazioni. Ma configurarli male causa bug subdoli: duplicati, retry infiniti, payload persi. In questa guida vediamo come gestirli bene.

Cosa sono

Un webhook è una HTTP POST che Shopify invia al tuo endpoint quando avviene un'evento. Il body contiene il payload JSON dell'oggetto interessato (ordine, prodotto, cliente). Devi rispondere HTTP 200 entro 5 secondi, altrimenti Shopify ritrasmette con backoff (fino a 19 tentativi in 48 ore).

Eventi disponibili

I topic più usati: orders/create, orders/updated, orders/cancelled, orders/fulfilled, orders/paid, products/create, products/update, products/delete, customers/create, customers/update, app/uninstalled, refunds/create, inventory_levels/update. Lista completa su shopify.dev/docs/api/webhooks.

Procedura passo-passo (via API)

1. Crea custom app con scope appropriato (es. read_orders).
2. Crea webhook via GraphQL mutation:
   mutation { webhookSubscriptionCreate(topic: ORDERS_CREATE, webhookSubscription: { callbackUrl: "https://miosito.it/webhook/orders", format: JSON }) { webhookSubscription { id } } }.
3. Implementa l'endpoint nel tuo backend.
4. Verifica autenticità via header X-Shopify-Hmac-Sha256: calcola HMAC SHA-256 del body con secret app e confronta.
5. Rispondi 200 immediatamente, processa async.
6. Gestisci idempotenza con header X-Shopify-Webhook-Id.
7. Logga tutti i webhook ricevuti per debug.
8. Configura alerting per webhook falliti (5XX).

Verifica HMAC (Node.js)

const crypto = require('crypto');
const hmac = req.headers['x-shopify-hmac-sha256'];
const generated = crypto
  .createHmac('sha256', SHOPIFY_API_SECRET)
  .update(body, 'utf8')
  .digest('base64');
if (generated !== hmac) return res.status(401).send('Invalid');

Idempotenza

Shopify può inviare lo stesso webhook più volte (retry o doppio invio): salva l'ID webhook in DB e ignora se già processato. L'header X-Shopify-Webhook-Id è univoco per delivery. In alternativa usa l'ID dell'oggetto (es. order.id) + timestamp per dedup.

Errori comuni e come risolverli

• Timeout 5 secondi: processo sincrono che chiama API esterne può superare; rispondi subito 200 e processa async (queue/job).
• HMAC non verificato: rischio attacco; sempre verifica HMAC.
• Webhook duplicati: senza idempotenza il sistema esterno (ERP) riceve doppi ordini; implementa controllo ID.
• Retry infinito: se rispondi sempre 500, Shopify riprova; logga e fixa.
• App uninstall: gestisci app/uninstalled per cleanup dati.

Domande frequenti

D: Posso vedere i webhook inviati storicamente?
R: Sì, su Partner Dashboard > App > Webhook deliveries; ultimi 48 ore visibili.

D: Quanti webhook posso configurare?
R: Nessun limite per topic, ma per performance evita oltre 30 webhook attivi.

D: I webhook funzionano offline?
R: No, serve endpoint pubblico HTTPS sempre raggiungibile.

Mandatory webhooks GDPR

Shopify obbliga le app pubbliche a gestire 3 webhook GDPR: customers/data_request (richiesta esportazione dati cliente), customers/redact (cancellazione dati cliente), shop/redact (cancellazione dati shop dopo uninstall). L'app deve rispondere entro 30 giorni con file dati o cancellazione confermata. Senza questi handler, app non passa review App Store. Configurali in shopify.app.toml:
[[webhooks.subscriptions]]
topics = ["customers/data_request"]
uri = "/webhooks/gdpr/data_request"

Queue per processing async

Per webhook ad alto volume non processare sincrono nell'handler: accoda il payload in Redis/SQS/RabbitMQ, rispondi 200, processa async in worker. Stack tipico Node.js: Express + BullMQ + Redis. Worker dedicato consuma jobs, retry on failure. Per Shopify Functions e App custom, hosting Heroku/Render con Worker dyno separato. Logging strutturato con request ID per debugging traceable.

Checklist operativa

Prima di considerare l'argomento implementato correttamente, verifica questa checklist sintetica: configurazione tecnica testata in ambiente di staging o development store, backup attivo prima di ogni modifica critica, documentazione interna aggiornata per il team operativo, training agli operatori che useranno la funzionalità, monitoraggio di metriche chiave (conversion rate, AOV, ticket support) per 30 giorni post-implementazione, revisione legale se l'implementazione tocca aspetti GDPR, fiscali o di pagamento, piano di rollback chiaro nel caso di problemi imprevisti, comunicazione ai clienti se il cambiamento influenza la loro esperienza (es. nuovo checkout, nuovi metodi di pagamento, nuovi tempi di spedizione). Una implementazione tecnica senza queste fasi di accompagnamento spesso non produce i risultati attesi e genera attriti interni o sui clienti.

Risorse utili e community

Per approfondire ulteriormente: la documentazione ufficiale Shopify su shopify.dev e help.shopify.com aggiorna costantemente le guide; il Shopify Community Forum ha thread attivi su quasi ogni argomento con risposte da Shopify Experts; Shopify Partner Academy offre corsi gratuiti per merchant e sviluppatori; YouTube channel ufficiale Shopify pubblica walkthrough delle nuove feature. Per il mercato italiano cerca community come Shopify Italia su Facebook o gruppi LinkedIn dedicati a e-commerce manager italiani: il confronto con altri merchant che vivono problemi simili è una scorciatoia preziosa rispetto a documentazione internazionale generica.

Una buona pratica supplementare è coinvolgere il proprio commercialista o consulente fiscale per qualsiasi configurazione che impatti su fatturazione, IVA o regimi speciali: in Italia ogni semplificazione tecnica deve essere accompagnata da verifica legale puntuale per evitare contestazioni successive. Allo stesso modo, valuta sempre l'impatto SEO di ogni cambiamento: monitora Search Console per le 4-6 settimane successive alla modifica, controlla che il numero di pagine indicizzate non cali e che le query principali continuino a posizionarsi. Per modifiche al tema, mantieni sempre una copia del tema precedente come fallback e documenta i cambiamenti in un changelog interno consultabile dal team. Una governance leggera ma costante è la differenza tra uno store che cresce nel tempo e uno che accumula debito tecnico nascosto.

Hai bisogno di aiuto?

Se vuoi un Shopify ottimizzato dal team di G Tech Group, scrivici tramite il modulo di contatto.