Come collegare i webhook standard a Shopify Flow
Standard Webhook è una specifica aperta per la firma dei webhook, utilizzata da OpenAI, Supabase Auth Hooks e da un numero sempre crescente di servizi. Un’unica impostazione predefinita li copre tutti. Workflow Webhooks trasforma tale chiamata in un trigger Shopify Flow, in modo che il Suo negozio possa reagire ad essa: contrassegnare un cliente, aggiungere una nota all’ordine, inviare un’e-mail interna, aggiornare un metacampo - qualsiasi cosa possa fare Shopify Flow.
La presente guida illustra l’intero percorso - Standard Webhook invia, Workflow Webhooks riceve e verifica, Shopify Flow agisce - con la firma HMAC di Standard Webhook verificata ad ogni richiesta, in modo che solo Standard Webhook possa avviare il Suo workflow.
Cosa potete realizzare
- Prenda un webhook di OpenAI - un’elaborazione in batch terminata o una risposta completata - e faccia in modo che Shopify Flow agisca in base al risultato nel Suo negozio.
- Reagisca a un hook di autenticazione Supabase, in modo che una registrazione nella Sua app associ il cliente corrispondente su Shopify.
- Ricevete dati da qualsiasi servizio che rispetti le specifiche di standardwebhooks.com senza dover configurare una firma personalizzata.
Eventi tipici da inviare: qualsiasi evento definito dal servizio di invio.
Lo stesso preset verifica anche i webhook provenienti da OpenAI e Supabase Auth Hooks.
Prima di iniziare
- Workflow Webhooks installato sul Suo negozio Shopify.
- Shopify Flow installata, disponibile gratuitamente dall’App Store all’indirizzo Shopify.
- Un account su Standard Webhook con l'autorizzazione a creare webhook.
Fase 1 - Creare il webhook all'indirizzo Workflow Webhooks
- Acceda a Workflow Webhooks -> Webhook -> Crea webhook e assegni al webhook un nome che potrà riconoscere in Shopify Flow, ad esempio
Standard Webhooks events. - Nella sezione "Autenticazione", selezionare HMAC.
- Nella sezione “Fornitore di firma”, selezioni “Webhook standard”. L’app inserisce automaticamente l’intestazione, l’algoritmo, il payload firmato e la finestra di replay: non è necessario configurare nient’altro.
- Per il momento lasci il campo "Segreto" vuoto e clicchi su "Salva". Copi l'URL del webhook visualizzato nella pagina.
Per ulteriori informazioni sulle altre modalità di autenticazione, consulti il sito Autenticazione; per scegliere quali campi inviare a Shopify Flow, consulti invece il sito Mappatura del payload e variabili di flusso.
Fase 2 - Aggiungere l'endpoint in "Webhook standard"
Aggiunga l'URL come endpoint nel servizio di invio, quindi copi il segreto di firma che le viene mostrato (che inizia con whsec_).
Come individuare il Suo segreto di firma per i Webhook standard
Il segreto di firma che inizia con whsec_. Lo incolli per intero; se viene visualizzato come v1,whsec_... (Supabase), ometta il "v1," iniziale.
La documentazione ufficiale di Standard Webhook sulle firme dei webhook, disponibile all’indirizzo, riporta il testo esatto e gli screenshot relativi al Suo account.
Inserisca tale codice segreto nel campo "Secret" del webhook all'indirizzo Workflow Webhooks e salvi. Da quel momento in poi, ogni invio effettuato tramite Standard Webhooks verrà verificato prima di raggiungere Shopify Flow.
Cosa verifica questa operazione
| Cosa | Valore |
|---|---|
| Intestazione della firma | webhook-signature |
| Dove si trova la firma | Il valore dell'intestazione, dopo il prefisso v1, |
| Cosa è stato firmato | {header:webhook-id}.{timestamp}.{body} |
| Firma | HMAC-SHA256, codificato in base64 |
| Data e ora | L'intestazione webhook-timestamp, espressa in secondi Unix |
| Protezione contro la riproduzione | Le richieste il cui timestamp firmato risale a più di 5 minuti fa vengono respinte |
| Il segreto | Decodificato in Base64 prima dell'uso. Il prefisso whsec_ viene rimosso prima della decodifica. Lo incolli esattamente come lo mostra il mittente |
Nel payload firmato, {body} rappresenta il corpo della richiesta in formato grezzo, byte per byte, mentre {timestamp} corrisponde al timestamp sopra indicato e {header:webhook-id} rappresenta l'intestazione della richiesta webhook-id.
Una richiesta che non soddisfi uno qualsiasi di questi requisiti viene respinta con l'errore 401, viene registrata in Cronologia e risoluzione dei problemi e non avvia mai un workflow.
Fase 3 - Creazione del workflow Shopify Flow
- In "Shopify Flow", crei un workflow e selezioni il trigger "Workflow Webhooks".
- Clicchi su “Registra eventi”, quindi invii un evento di prova da “Webhook standard” (oppure utilizzi l’opzione “Invia prova” in Workflow Webhooks) in modo che Shopify Flow apprenda la struttura dei Suoi dati.
- Ogni webhook di cui disponete attiva lo stesso trigger del flusso; pertanto, aggiungete una prima condizione relativa all’ID del webhook per limitare questo workflow esclusivamente ai webhook standard. L’ID è riportato nella pagina dedicata ai webhook.
- Aggiunga le Sue azioni: contrassegni un cliente, aggiunga una nota, invii un’e-mail interna, aggiorni un metacampo.
Fase 4 - Eseguire un test end-to-end
Attivare un evento reale in Standard Webhooks. In Workflow Webhooks -> Cronologia dovrebbe apparire la richiesta con lo stato “Successo”. Se la firma non era corretta, verrà invece visualizzata una voce con lo stato “Fallito” e il motivo corrispondente; inoltre, all’indirizzo Verifica dei webhook firmati è disponibile lo strumento di verifica della firma che indica esattamente quale fase non è andata a buon fine.
La firma non corrisponde▾
In questo ordine: il segreto (la causa più comune: uno spazio in eccesso o una chiave proveniente da un ambiente errato), se il mittente sta utilizzando il segreto di un endpoint diverso e se, tra gli Standard Webhook e l’app, vi è qualcosa che riscrive il corpo del messaggio. Le firme coprono i byte grezzi, pertanto un proxy che riformatta il JSON le invalida. Il tester di firme nella pagina dei webhook mostra il testo esatto che è stato firmato.
Ricevo un errore 401 ad ogni richiesta▾
Verifichi che l'autenticazione del webhook sia impostata su HMAC con il provider "Standard Webhook" selezionato, che il segreto sia stato inserito e che "Standard Webhook" invii i dati all'URL esattamente come indicato dall'app, compreso il codice alla fine.
Nella cronologia non compare nulla▾
La richiesta non è mai pervenuta. Verifichi nuovamente l'URL in Standard Webhooks e controlli il registro di consegna di Standard Webhooks per vedere quale risposta è stata ricevuta. Un codice di errore 404 indica un webhook errato o eliminato, mentre un codice 429 significa che ha superato il limite di invocazioni previsto dal Suo piano; si veda Piani e utilizzo.
Il workflow viene eseguito per eventi non corretti▾
Ogni webhook del Suo negozio attiva lo stesso trigger di Shopify Flow. Aggiunga una condizione relativa all’ID del webhook come primo passo del workflow, oppure restringa la selezione degli eventi inviati dai webhook standard.
Le richieste falliscono con il messaggio "timestamp fuori dai limiti di tolleranza"▾
Standard Webhook appone un timestamp e l'app rifiuta qualsiasi evento risalente a più di 5 minuti fa. Si tratta in genere di un problema di sincronizzazione da parte del mittente, oppure di una consegna che Standard Webhook ha riprovato a effettuare molto più tardi utilizzando il timestamp originale. I tentativi di ripetizione della stessa richiesta originale non possono essere accettati; si prega di chiedere a Standard Webhook di inviare un nuovo evento.
Correlati
- Verifica dei webhook firmati - ogni fornitore che verifichiamo e come descrivere quelli che non verifichiamo.
- Mappatura del payload e variabili di flusso - estrarre i campi corretti dal payload e inserirli in Shopify Flow.
- Protezione contro le consegne duplicate - cosa accade quando Standard Webhooks effettua un nuovo tentativo di consegna.
- Cronologia e risoluzione dei problemi - il registro di ogni richiesta, con la possibilità di riprodurla.