Come collegare Paddle a Shopify Flow
Paddle è un operatore di pagamento ufficiale per prodotti digitali e abbonamenti. Vi invia notifiche relative a transazioni, abbonamenti, rimborsi e modifiche apportate dai clienti. Workflow Webhooks trasforma tale notifica in un Trigger “Shopify Flow”, in modo che il vostro 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 operazione che Shopify Flow sia in grado di eseguire.
La presente guida illustra l’intero percorso - Paddle invia, Workflow Webhooks riceve e verifica, Shopify Flow agisce - con la firma HMAC di Paddle verificata ad ogni richiesta, in modo che solo Paddle possa avviare il Suo workflow.
Cosa potete realizzare
- Tag un cliente Shopify che disponga anche di un abbonamento a Paddle, in modo che possa visualizzare i prezzi o i contenuti corretti.
- Invii un’e-mail al Suo team quando un abbonamento viene disdetto e il cliente ha effettuato ordini recenti su Shopify.
- Inserisca il piano attuale nella scheda del cliente come metacampo.
Eventi tipici da inviare: transaction.completed, subscription.canceled, adjustment.created (rimborso), customer.updated.
Prima di iniziare
- Workflow Webhooks installato sul Suo negozio Shopify.
- Shopify Flow installata, disponibile gratuitamente nell’App Store all’indirizzo Shopify.
- Un account su Paddle 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
Paddle events. - Nella sezione "Autenticazione", selezioni HMAC.
- Nella sezione “Fornitore di firma”, selezionate Paddle. 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 vengano trasmessi a Shopify Flow, consulti il sito Mappatura del payload e variabili di flusso.
Fase 2 - Aggiungere l'endpoint in Paddle
In Paddle, apra Strumenti di sviluppo -> Notifiche, aggiunga una destinazione con l’URL che ha copiato e selezioni gli eventi. La chiave segreta è visibile nella destinazione.
Come individuare il Suo codice segreto per la firma su Paddle
La chiave segreta della destinazione delle notifiche (Paddle -> Strumenti per sviluppatori -> Notifiche).
La documentazione ufficiale di Paddle 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 consegna effettuata tramite Paddle verrà verificata prima di raggiungere Shopify Flow.
Cosa verifica questa operazione
| Cosa | Valore |
|---|---|
| Intestazione della firma | Paddle-Signature |
| Dove si trova la firma | Nel valore h1 di tale intestazione, che contiene coppie key=value separate da punti e virgola |
| Cosa è stato firmato | {timestamp}:{body} |
| Firma | HMAC-SHA256, codificato in esadecimale |
| Data e ora | Il valore ts 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. Incollatelo esattamente come lo presenta il mittente |
Nel payload firmato, {body} rappresenta il corpo della richiesta non elaborato, 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 - 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 Paddle (oppure utilizzi l’opzione “Invia prova” in Workflow Webhooks) in modo che Shopify Flow apprenda la struttura dei Suoi dati.
- Ogni webhook di cui dispone attiva lo stesso trigger di Shopify Flow; pertanto, aggiunga una prima condizione basata sull’ID del webhook per limitare questo workflow esclusivamente a Paddle. 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
Trigger un evento reale in Paddle. In Workflow Webhooks -> Cronologia dovrebbe essere visibile 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 ha superato il controllo.
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 qualcosa tra Paddle 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 Paddle selezionato, che il codice segreto sia stato inserito e che Paddle 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 Paddle e controlli il registro di consegna di Paddle per verificare la risposta ricevuta. Un codice di errore 404 indica un webhook errato o cancellato, mentre un codice 429 significa che ha superato il limite di invocazioni previsto dal Suo piano; 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 basata sull’ID del webhook come primo passo del workflow, oppure restringa la selezione degli eventi che invia da Paddle.
Le richieste falliscono con il messaggio "timestamp fuori tolleranza"▾
Paddle 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 dell’orologio sul lato mittente, oppure di un evento che Paddle 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 richiedere a Paddle 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 Paddle riprova a effettuare una consegna.
- Cronologia e risoluzione dei problemi - il registro di ogni richiesta, con la possibilità di riprodurla.