Creare il Suo primo webhook

Questa guida vi accompagnerà dalla creazione di un’applicazione vuota alla realizzazione di un workflow Shopify Flow che si avvia quando il vostro sistema lo richiede. Ci vorranno circa dieci minuti.

1. Creare un webhook

Webhook -> Crea webhook. La pagina chiede innanzitutto quale elemento attiverà questo webhook e lo configura di conseguenza:

La Sua risposta	Cosa riceverete
Uno strumento di automazione (n8n, Make, Zapier, codice personalizzato)	Un token generato, pronto per essere incollato nello strumento
Un servizio che firma i propri webhook (Stripe, GitHub, ...)	Verifica della firma per il servizio da Lei scelto - consulti il sito Verifica dei webhook firmati
Uno script per browser o per vetrina online	CORS attivato - si veda CORS, l'URL del proxy dell'app e le richieste del browser
Niente: esegua l'operazione secondo una pianificazione	Un webhook che recupera un URL a intervalli regolari; la scheda “Pianificazione” si apre immediatamente dopo - si veda Interrogazione periodica degli URL
Qualcos’altro, oppure deciderò in seguito	Siete voi stessi a scegliere la modalità di autenticazione

Assegnate un nome che potrete riconoscere in seguito ("Promemoria carta da portafoglio", "Modulo di contatto") e salvate. Ogni impostazione potrà essere modificata in un secondo momento.

Ora dispone di un URL di webhook che termina con un codice breve, ad esempio https://.../webhook/ab12cd34. Tale URL rappresenta l'endpoint a cui il Suo sistema invia le richieste POST.

Nella pagina “Crea webhook”, in cui viene chiesto “Cosa attiverà questo webhook?”, è stata selezionata l’opzione “Nessuna - eseguirlo secondo una pianificazione” e viene indicato che la scheda “Pianificazione” si aprirà successivamente — Per creare un webhook occorre innanzitutto stabilire cosa lo attiverà. La risposta configura l’autenticazione corrispondente; selezionando “Niente - eseguirlo a intervalli regolari” si apre la scheda “Pianificazione”.

L'editor dei webhook: nome e autenticazione a sinistra; la scheda "Endpoint" con stato, URL del webhook e ID del webhook a destra; in alto, "Anteprima in tempo reale", "Prova" e "Utilizzo" — L'editor dei webhook. Le impostazioni si trovano a sinistra; la scheda "Endpoint" a destra contiene l'URL del webhook da fornire al mittente e l'ID del webhook da utilizzare in Shopify Flow.

2. Scegliete in che modo i chiamanti devono dimostrare la propria identità

Apra il webhook e scelga un metodo di autenticazione. Per un confronto completo, consulti Autenticazione; in sintesi:

Token statico: adatto praticamente a tutti. Premete il pulsante “Genera”, copiate il token, Inviatelo nell'intestazione X-Api-Key.
HMAC SHA-256 - per i mittenti che firmano le proprie richieste (Stripe, GitHub e simili).
Nessuno - solo a scopo di test. Chiunque disponga dell’URL può avviare il Suo workflow.

3. Ci indichi quali sono i settori di Suo interesse

Nella sezione "Impostazioni avanzate", è possibile mappare fino a quattro campi del proprio payload JSON. Se il proprio sistema invia:

La scheda “Impostazioni avanzate” con i campi da 1 a 4 associati rispettivamente a orderId, status, total e note — Impostazioni avanzate: è possibile associare fino a quattro valori dal corpo della richiesta. Questi valori vengono inviati in Shopify Flow come fieldOne, fieldTwo, fieldThree e fieldFour.

json

{ "customer": { "email": "someone@example.com" }, "orderId": "1001" }

Mappare fieldOne a orderId e fieldTwo a customer.email - per i percorsi annidati si utilizzino i punti. Maggiori dettagli sono disponibili all'indirizzo Mappatura del payload e variabili di flusso.

4. Inviare una richiesta di prova

Un'invocazione aperta in History con le intestazioni della richiesta, il payload, lo stato, la durata e gli identificatori — A seguito di una richiesta di test, l'invocazione compare nella Cronologia insieme al payload ricevuto.

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001","customer":{"email":"someone@example.com"}}'

Apra la cronologia. Dovrebbe visualizzare la richiesta con il relativo stato, le intestazioni e il payload. Se non è presente, all’indirizzo Cronologia e risoluzione dei problemi sono elencati tutti i motivi di rifiuto.

5. Creare il workflow in Shopify Flow

In "Shopify Flow", crei un workflow che inizi con il trigger "Webhook Trigger".

Aggiunga il trigger e faccia clic su “Registra eventi”.
Torni qui, apra l’invocazione nella cronologia e prema “Riproduci”. Shopify Flow ora presenta un un esempio concreto di payload su cui lavorare - molto più semplice che cercare di indovinare i nomi dei campi.
Aggiungere una condizione: Webhook ID deve corrispondere all’ID del Suo webhook (visualizzato nella pagina dedicata al webhook). Ogni workflow "Webhook Trigger" riceve eventi da tutti i Suoi webhook, pertanto questo È proprio questa condizione a far sì che il workflow risponda esclusivamente a questa.
Aggiunga le Sue azioni, utilizzando l'indirizzo {{fieldOne}} per inviare un'e-mail a {{fieldFour}}.
Attivi il workflow.

Si è aperto il simbolo “+” sotto la fase “Webhook Trigger”, mostrando le opzioni “Azione” e “Condizione” — Il simbolo “+” sotto un passaggio offre gli elementi fondamentali di cui è composto un workflow: una condizione e un’azione.

Condizione del flusso: l’ID del webhook è uguale all’ID di un webhook — Il primo passo di ogni workflow: una condizione relativa all’ID del webhook, in modo che il workflow venga eseguito solo per questo webhook.

Il pannello “Aggiungi una variabile” di Shopify Flow per il trigger Webhook, che elenca webhookId e da fieldOne a fieldFour con valori di esempio tratti da una richiesta recente — Ecco cosa fornisce il trigger al Suo workflow: l’ID del webhook e i Suoi quattro campi mappati, riportati con i valori di una richiesta recente.

L'azione "Invia e-mail interna" di Shopify Flow con fieldOne e fieldTwo nell'oggetto e fieldThree e fieldFour nel corpo del messaggio — Utilizzi i campi mappati ovunque un'azione di Shopify Flow richieda una variabile, in questo caso nell'oggetto e nel corpo di un'e-mail interna.

Il workflow completato: trigger webhook, una condizione relativa all’ID del webhook, quindi invio di un’e-mail interna nel ramo “True” — Il workflow completato: trigger, condizione basata sull’ID del webhook, quindi la vostra azione sul ramo “True”.

6. Pubblicare

Configuri il Suo sistema reale in modo che utilizzi l'URL del webhook. Verifichi le prime chiamate nella sezione "Cronologia" per assicurarsi che arrivino a destinazione e vadano a buon fine.

Se il mittente effettua un nuovo tentativo al termine del timeout, attivi l'opzione Protezione contro le consegne duplicate (Non consentire i tentativi ripetuti) in modo che un nuovo tentativo non possa eseguire il workflow due volte.

La pagina “Webhook” che elenca sei webhook, ciascuno con il proprio conteggio delle chiamate, le informazioni di autenticazione e un indicatore che ne segnala lo stato (Abilitato o Disabilitato) — La pagina “Webhook”. Ogni riga mostra la frequenza con cui il webhook è stato richiamato, le modalità di autenticazione dei chiamanti e se è abilitato; il menu a destra consente di abilitarlo, disabilitarlo o eliminarlo.