API per sviluppatori e MCP

Tutto ciò che gestite nell’app potete gestirlo anche tramite il vostro codice o tramite un assistente AI. Workflow Webhooks mette a disposizione due interfacce: un’API REST e un server MCP. Entrambe sono disponibili nella pagina “Developer”.

Chiavi API

Entrambe le piattaforme effettuano l'autenticazione tramite una chiave API. Nella pagina "Sviluppatori", alla voce "Chiavi API", crei una chiave e ne selezioni il livello di accesso:

Solo lettura: elencare i webhook, visualizzare la cronologia delle chiamate e le statistiche.
Lettura e scrittura: è inoltre possibile creare, aggiornare ed eliminare i webhook.
Leggere, scrivere ed eseguire: è inoltre possibile avviare una chiamata di prova o riprodurre una chiamata precedente.

La chiave completa viene visualizzata una sola volta, al momento della creazione. La si deve copiare in quel momento e conservarla in un luogo sicuro; non sarà più possibile visualizzarla. Le chiavi vengono archiviate sotto forma di hash, mai in chiaro, ed è possibile revocare una chiave in qualsiasi momento.

Inviare la chiave come token "Bearer" in ogni richiesta:

text

Authorization: Bearer fwk_your_key_here

Perché l’esecuzione costituisce un livello a sé stante

L’attivazione di un Webhook avvia effettivamente i Workflow di Shopify Flow, e tali Workflow possono apportare modifiche al Suo negozio: assegnare tag agli ordini, inviare e-mail, aggiornare l’inventario. Mantenere questa funzione a un livello separato significa che una chiave che Lei fornisce a uno script o a un assistente IA per le attività quotidiane non potrà attivare accidentalmente le Sue automazioni. Assegnate chiavi di lettura per impostazione predefinita e create una chiave di esecuzione solo laddove ne abbiate realmente bisogno.

URL di base

L'API e il server MCP sono ospitati su un nome host dedicato:

text

https://shopify.workflow-webhooks.app

Pertanto, l’API REST è disponibile all’indirizzo https://shopify.workflow-webhooks.app/api/v1 e il server MCP all’indirizzo https://shopify.workflow-webhooks.app/api/mcp. La pagina “Sviluppatori” mostra entrambi i link, corredati da un pulsante “Copia”.

Questo nome host serve esclusivamente /api - l'interfaccia utente di amministrazione incorporata rimane sul proprio URL registrato Shopify. Tenendoli separati, l'indirizzo che inserite in uno script, in un processo CI o in un client AI risulta stabile e indipendente dall'incorporamento dell'applicazione.

API REST

L'URL di base è riportato nella pagina "Sviluppatori". Gli endpoint principali sono:

Metodo	Percorso	Livello	Finalità
GET	`/api/v1`	nessuno	Indice API - conferma che l'API è attiva
GET	`/api/v1/me`	leggere	Verifichi l’autenticazione e controlli il livello della Sua chiave
GET	`/api/v1/webhooks`	leggere	Elenco dei webhook
POST	`/api/v1/webhooks`	scrivere	Creare un webhook
GET	`/api/v1/webhooks/:id`	leggere	Ottenga un webhook
PUT / PATCH	`/api/v1/webhooks/:id`	scrivere	Aggiornare un webhook
ELIMINA	`/api/v1/webhooks/:id`	scrivere	Eliminare un webhook
POST	`/api/v1/webhooks/:id/test`	eseguire	Eseguire una chiamata di prova
GET	`/api/v1/history`	leggere	Elenco delle chiamate
GET	`/api/v1/history/:id`	leggere	Ottenere una chiamata, con il relativo payload
POST	`/api/v1/history/:id/replay`	eseguire	Riprodurre un'invocazione precedente
GET	`/api/v1/stats`	leggere	Totali, percentuale di successo, serie giornaliere
GET	`/api/v1/templates`	leggere	Modelli di webhook integrati

Una rapida verifica per assicurarsi che la chiave funzioni:

bash

curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"

json

{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

Server MCP

Il server MCP consente a un assistente IA (Claude, Cursor, VS Code, Gemini CLI e altri) di interagire con i Suoi webhook durante la conversazione. Nella pagina “Sviluppatori”, la scheda “MCP” mostra l’URL del server e un comando di connessione pronto per essere copiato per ciascun client, con la Sua chiave già inserita.

Gli strumenti rispecchiano gli endpoint REST e il set di strumenti riflette il livello della vostra chiave: una chiave di sola lettura non ha nemmeno accesso agli strumenti che consentono di creare, eliminare o attivare i webhook. Tutte le operazioni di autenticazione e di gestione dei dati avvengono lato server.

Come vengono protetti i Suoi dati

Prima di utilizzare un sistema di automazione o un assistente basato sull’intelligenza artificiale con questa API, è opportuno tenere presenti due aspetti.

Il token di autenticazione del Suo webhook non è mai leggibile. Il token o il segreto di firma che ha impostato su un webhook non può essere recuperato tramite l’API o l’MCP a nessun livello. Le risposte indicano solo se un token è stato impostato (hasToken), mai il suo valore. È possibile impostarne uno nuovo; non è mai possibile recuperare quello precedente.

I dati personali presenti nei payload vengono mascherati. I payload dei webhook provengono da sistemi esterni e spesso contengono informazioni relative ai clienti. Prima che un payload di invocazione lasci il server, i valori che sembrano dati personali vengono sostituiti con un codice di mascheramento (***): indirizzi e-mail, numeri di telefono, numeri di carta di credito e campi che riportano il nome di una persona (ad esempio customerName, shippingAddress e simili). Le intestazioni delle richieste vengono sottoposte a sanitizzazione allo stesso modo in cui avviene nella schermata della cronologia dell’app.

Questa operazione di mascheramento è accurata, ma non costituisce una garanzia. Agisce sui nomi dei campi e sugli schemi dei valori; pertanto, i dati personali contenuti all’interno di un campo di testo libero - una nota, un commento, il corpo di un messaggio - potrebbero comunque essere visibili. Consideri le risposte delle API come potenzialmente contenenti dati dei clienti e le archivi di conseguenza.

I test e i replay non consumano la Sua quota. Le chiamate che effettua tramite l’API vengono registrate come test, pertanto non vengono conteggiate ai fini del limite mensile previsto dal Suo piano. Anche i replay non vengono conteggiati, poiché la chiamata originale è già stata conteggiata.

Prossimi passi

Introduzione a Workflow Webhooks - come funzionano i webhook e la mappatura dei payload.

Limiti di frequenza

L'API REST e il server MCP condividono un unico budget per ogni chiave API.

300 richieste ogni 60 secondi per chiave, in una finestra fissa.
Le chiamate a livello di esecuzione dispongono di un secondo budget, più limitato, pari a 60 all’ora. Poiché consumano entrambi, un picco di esecuzioni intacca anche la quota condivisa. Per questa app ciò significa l’attivazione di prova di un webhook e la riproduzione di una voce della cronologia, entrambe operazioni che avviano effettivamente i workflow di Shopify Flow.
È lo stesso per tutti i piani. Il Suo piano limita il numero di invocazioni, non di chiamate API, pertanto il passaggio a un piano superiore non comporta un aumento di tali valori.
Viene restituito il codice di stato HTTP 429. Si raccomanda di attendere e riprovare, preferibilmente con un backoff esponenziale.
Qualora la nostra cache risultasse temporaneamente non disponibile, il limitatore adotterà una modalità di funzionamento “fail-open” anziché bloccare la vostra integrazione.

Incoming webhooks are not subject to frequency limitations

È opportuno chiarirlo, poiché è la domanda che ci viene posta più spesso: non limitiamo la velocità di invio dei webhook in entrata. Li inoltriamo non appena arrivano, indipendentemente dal volume che il vostro sistema di origine è in grado di generare: da parte nostra non vi è alcun limite al secondo o al minuto.

L'unico limite è **la quota di 30 giorni **prevista dal Suo piano. Una volta esaurita tale quota, le ulteriori chiamate non verranno più elaborate fino al rinnovo del periodo di validità o fino a quando non effettuerà un upgrade. Oltre a ciò, si applicano i limiti previsti da Shopify: Shopify Flow ha i propri limiti di esecuzione e il payload di un trigger è limitato a 50 KB.

Shopify

Si tratta dei limiti imposti da Shopify alle API di Shopify, non dei nostri. Essi si applicano a ciò che questa app (e i Suoi workflow) può fare dal punto di vista di Shopify, ed è possibile che li raggiunga nel caso di un negozio di grandi dimensioni, anche pur rimanendo ben al di sotto dei nostri limiti.

Gli array di input sono limitati a 250 elementi in tutte le API Shopify. Una richiesta contenente un array più ampio viene respinta.
L'impaginazione si interrompe a 25.000 oggetti. I conteggi sono precisi fino a 25.000; oltre tale soglia, lShopifye restituisce "25001, ovvero "più di 25.000". Se avete bisogno di approfondire la ricerca, applicate prima un filtro.
L'API di amministrazione GraphQL è soggetta a un limite basato sul costo calcolato delle query, espresso in punti al secondo, e il limite massimo dipende dal piano Shopify del negozio:

Shopify piano	Punti al secondo
Standard	100
Avanzato	200
Inoltre	1000
Enterprise (Componenti commerciali)	2000

L'API della vetrina online non è soggetta a limitazioni di frequenza.

Dettagli completi: Limiti di utilizzo dell’API di Shopify