Come collegare Stripe a Shopify Flow
Stripe è una piattaforma di pagamento. Invia un Webhook per ogni pagamento, rimborso, contestazione, modifica dell’abbonamento ed evento relativo alle fatture nel Suo account. Workflow Webhooks trasforma tale chiamata in un trigger di Shopify Flow, in modo che il Suo negozio possa reagire di conseguenza: assegnare un Tag a un cliente, aggiungere una nota all’ordine, inviare un’e-mail interna, aggiornare un metacampo - qualsiasi cosa Shopify Flow sia in grado di fare.
La presente guida illustra l’intero percorso - Stripe invia, Workflow Webhooks riceve e verifica, Shopify Flow agisce - con la firma HMAC di Stripe verificata ad ogni richiesta, in modo che nessun altro soggetto, se non Stripe, possa avviare il Suo workflow.
Cosa potete realizzare
- Tag un cliente di Shopify che abbia effettuato il pagamento tramite un checkout Stripe o un link di pagamento, in modo che i Suoi segmenti rimangano sincronizzati.
- Aggiunga una nota all’ordine e avvisi il Suo team non appena viene aperta una controversia.
- Inviate un’e-mail al personale quando il pagamento di un abbonamento non va a buon fine, in modo che qualcuno possa contattare il cliente prima che questo si allontani.
Eventi tipici da inviare: payment_intent.succeeded, charge.refunded, charge.dispute.created, customer.subscription.deleted, invoice.payment_failed.
Prima di iniziare
- Workflow Webhooks installato sul Suo negozio Shopify.
- Shopify Flow installata, disponibile gratuitamente dall’App Store all’indirizzo Shopify.
- Un account su Stripe 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 possa riconoscere in Shopify Flow, ad esempio
Stripe events. - Nella sezione "Autenticazione", selezionare HMAC.
- Nella sezione “Fornitore di firma”, selezioni Stripe. 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 sapere quali campi vengono trasmessi a Shopify Flow, consulti il sito Mappatura del payload e variabili di flusso.
Fase 2 - Aggiungere l'endpoint in Stripe
Nella dashboard di Stripe, apra la sezione Sviluppatori -> Webhook, aggiunga un endpoint con l'URL che ha copiato e selezioni gli eventi che desidera inviare.
Come individuare il proprio segreto di firma Stripe
Codice segreto di firma del webhook (whsec_...) disponibile nella dashboard di Stripe -> Sviluppatori -> Webhook.
La documentazione ufficiale di Stripe sulle firme dei webhook, disponibile all'indirizzo, riporta il testo esatto e le schermate relative al Suo account.
Inserisca tale codice segreto nel campo "Secret" del webhook all'indirizzo Workflow Webhooks e salvi. Da quel momento in poi, ogni transazione Stripe verrà verificata prima di raggiungere Shopify Flow.
Cosa verifica questa operazione
| Cosa | Valore |
|---|---|
| Intestazione della firma | Stripe-Signature |
| Dove si trova la firma | Nel valore v1 di tale intestazione, che contiene coppie key=value separate da virgole |
| Cosa è stato firmato | {timestamp}.{body} |
| Firma | HMAC-SHA256, codificato in esadecimale |
| Data e ora | Il valore t dell’intestazione della firma, espresso in secondi Unix |
| Protezione contro la riproduzione | Le richieste il cui timestamp firmato risale a più di 5 minuti fa vengono respinte |
| Il segreto | Da utilizzare come testo semplice. Lo incolli esattamente come lo presenta il mittente |
Nel payload firmato, {body} rappresenta il corpo della richiesta in formato grezzo, byte per byte, mentre {timestamp} corrisponde al timestamp sopra indicato.
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 - Creare il 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 Stripe (oppure utilizzi la funzione “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 Shopify Flow; pertanto, aggiungete una prima condizione relativa all’ID del webhook per limitare questo workflow esclusivamente a Stripe. 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
Attivi un evento reale in Stripe. In Workflow Webhooks -> Cronologia dovrebbe visualizzare la richiesta con lo stato “Success”. Se la firma non era corretta, verrà invece visualizzata una voce di errore con il motivo corrispondente; all’indirizzo Verifica dei webhook firmati è disponibile il tester di firma che le mostra 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 dall’ambiente sbagliato), se il mittente sta utilizzando il segreto di un endpoint diverso e se qualcosa tra Stripe e l’app riscrive il corpo del messaggio. Le firme coprono i byte grezzi, pertanto un proxy che riformatta il JSON le invalida. Il tester delle firme nella pagina del 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 Stripe selezionato, che il segreto sia stato inserito e che Stripe 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 Stripe e consulti il registro delle consegne di Stripe per verificare la risposta 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; per ulteriori informazioni, consulti 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 da Stripe.
Le richieste falliscono con il messaggio "timestamp fuori tolleranza"▾
Stripe appone un timestamp e l’app rifiuta qualsiasi evento risalente a più di 5 minuti fa. Si tratta solitamente di un problema di sincronizzazione dell’orologio da parte del mittente, oppure di un evento che Stripe ha ritentato di inviare molto più tardi mantenendo il timestamp originale. I tentativi successivi relativi alla stessa richiesta originale non possono essere accettati; si prega di chiedere a Stripe 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 succede quando Stripe riprova a effettuare un pagamento.
- Cronologia e risoluzione dei problemi - il registro di ogni richiesta, con la possibilità di riprodurla.