Jak połączyć Paddle zShopify Flow
Połącz Paddle z Shopify Flow przez webhooki z weryfikacją HMAC i automatycznie dodawaj tagi, notatki do zamówień oraz metapola po zdarzeniach Paddle.
Paddle pełni rolę oficjalnego sprzedawcy produktów cyfrowych i subskrypcji. Powiadamia Państwa o transakcjach, subskrypcjach, zwrotach środków oraz zmianach dotyczących klientów. Funkcja Workflow Webhooks przekształca to powiadomienie w wyzwalacz Shopify Flow, dzięki czemu Państwa sklep może na nie zareagować: przypisać tag do klienta, dodać notatkę do zamówienia, wysłać wewnętrzną wiadomość e-mail, zaktualizować metapole - czyli wykonać każdą czynność, do której umożliwia Shopify Flow.
Niniejszy przewodnik opisuje cały proces - Paddle wysyła dane, usługa Workflow Webhooks je odbiera i weryfikuje, a Shopify Flow podejmuje odpowiednie działania - przy czym w każdym żądaniu sprawdzany jest podpis HMAC firmy Paddle, dzięki czemu wyłącznie Paddle może uruchomić Państwa przepływ pracy.
Co można zbudować
- Proszę oznaczyć klienta Shopify, który posiada również subskrypcję Paddle, aby mógł zobaczyć odpowiednie ceny lub treści.
- Proszę wysłać wiadomość e-mail do swojego zespołu, gdy subskrypcja zostanie anulowana, a klient ma niedawne zamówienia w Shopify.
- Proszę wprowadzić aktualny plan do karty klienta jako metapole.
Typowe zdarzenia, które należy wysyłać: transaction.completed, subscription.canceled, adjustment.created (zwrot kosztów), customer.updated.
Zanim zaczną Państwo
- Webhooki Workflow Webhooks zainstalowane w Państwa sklepie Shopify.
- Zainstalowano aplikację Shopify Flow, którą można pobrać bezpłatnie ze sklepu Shopify App Store.
- Konto w serwisie Paddle z uprawnieniami do tworzenia webhooków.
Krok 1 - Utwórz webhook w sekcji Workflow Webhooks
- Proszę otworzyć sekcję Workflow Webhooks → Webhooks → Utwórz webhook i nadać mu nazwę, którą będą Państwo w stanie rozpoznać w Shopify Flow, na przykład
Paddle events. - W sekcji Uwierzytelnianie proszę wybrać opcję HMAC.
- W sekcji Dostawca podpisu proszę wybrać opcję Paddle. Aplikacja automatycznie wypełni pola dotyczące nagłówka, algorytmu, podpisanej treści oraz okna odtworzenia - nie ma potrzeby konfigurowania żadnych innych ustawień.
- Na razie proszę pozostawić pole „secret” puste i kliknąć Zapisz. Proszę skopiować adres URL webhooka wyświetlony na stronie.
Informacje na temat pozostałych trybów uwierzytelniania można znaleźć w sekcji Uwierzytelnianie, a informacje dotyczące wyboru pól, które mają zostać przesłane do Shopify Flow - w sekcji Mapowanie danych użytkowych i zmienne w Shopify Flow.
Krok 2 - Dodaj punkt końcowy w Paddle
W aplikacji Paddle proszę otworzyć sekcję Narzędzia programisty → Powiadomienia, dodać miejsce docelowe z skopiowanym adresem URL oraz wybrać odpowiednie zdarzenia. Tajny klucz jest widoczny w miejscu docelowym.
Jak znaleźć swój sekretny klucz do podpisywania w systemie Paddle
Klucz tajny miejsca docelowego powiadomień (Paddle → Narzędzia programistyczne → Powiadomienia).
W dokumentacji serwisu Paddle dotyczącej podpisów webhooków znajdą Państwo dokładne sformułowania oraz zrzuty ekranu dotyczące Państwa konta.
Wklej ten klucz tajny w polu Secret webhooka w sekcji Workflow Webhooks i zapisz zmiany. Od tego momentu każda dostawa z serwisu Paddle będzie weryfikowana przed dotarciem do Shopify Flow.
Co to sprawdza
| Co | Wartość |
|---|---|
| Nagłówek podpisu | Paddle-Signature |
| Miejsce umieszczenia podpisu | W wartości h1 tego nagłówka, która zawiera pary key=value, oddzielone średnikami |
| Co zostało podpisane | {timestamp}:{body} |
| Podpis | HMAC-SHA256, zakodowany w systemie szesnastkowym |
| Sygnatura czasowa | Wartość ts w nagłówku podpisu, wyrażona w sekundach systemu Unix |
| Ochrona przed ponownym odtworzeniem | Żądania, których podpisany znacznik czasu odbiega od chwili obecnej o ponad 5 minut, są odrzucane |
| Sekret | Należy użyć jako zwykły tekst. Proszę wkleić go dokładnie tak, jak przedstawił go nadawca |
W podpisanej treści {body} stanowi surową treść żądania, bajt po bajcie, a {timestamp} to powyższy znacznik czasu.
Żądanie, które nie spełnia któregokolwiek z tych warunków, jest odrzucane z kodem błędu 401, rejestrowane w sekcji Historia i rozwiązywanie problemów i nigdy nie uruchamia przepływu pracy.
Krok 3 - Utwórz proces w Shopify Flow
- W Shopify Flow proszę utworzyć przepływ pracy i wybrać wyzwalacz Workflow Webhooks.
- Proszę kliknąć opcję Rejestruj zdarzenia, a następnie wysłać zdarzenie testowe z serwisu Paddle (lub skorzystać z opcji Wyślij zdarzenie testowe w sekcji Workflow Webhooks), aby Shopify Flow rozpoznał strukturę Państwa danych.
- Każdy posiadany przez Państwa webhook uruchamia ten sam wyzwalacz w Shopify Flow, dlatego prosimy o dodanie pierwszego warunku opartego na identyfikatorze webhooka, aby ten przepływ pracy dotyczył wyłącznie serwisu Paddle. Identyfikator ten jest widoczny na stronie webhooka.
- Proszę dodać swoje działania - oznaczyć klienta, dodać notatkę, wysłać wewnętrzną wiadomość e-mail, zaktualizować metapole.
Krok 4 - Przeprowadź test od początku do końca
Wywołaj rzeczywiste zdarzenie w Paddle. W sekcji Workflow Webhooks → Historia powinno pojawić się wywołanie o statusie Success. Jeśli podpis był nieprawidłowy, pojawi się zamiast tego wpis o niepowodzeniu wraz z przyczyną, a Weryfikacja podpisanych webhooków zawiera wyjaśnienie narzędzia do weryfikacji podpisu, które wskazuje dokładnie, który etap zakończył się niepowodzeniem.
Podpis nie jest zgodny
W następującej kolejności: klucz tajny (najczęstsza przyczyna - dodatkowa spacja lub klucz z niewłaściwego środowiska), czy nadawca korzysta z klucza tajnego innego punktu końcowego oraz czy coś pomiędzy Paddle a aplikacją zmienia treść wiadomości. Podpisy obejmują surowe bajty, więc serwer proxy, który zmienia format JSON, unieważnia je. Narzędzie do sprawdzania podpisów na stronie webhooka wyświetla dokładny tekst, który został podpisany.
Przy każdym żądaniu otrzymuję kod błędu 401
Proszę sprawdzić, czy w ustawieniach uwierzytelniania webhooka wybrano opcję HMAC z dostawcą Paddle, czy wpisano klucz tajny oraz czy Paddle wysyła dane na adres URL dokładnie taki, jak pokazano w aplikacji, łącznie z kodem na końcu.
W historii nie ma żadnych wpisów
Żądanie nigdy nie dotarło. Proszę ponownie sprawdzić adres URL w serwisie Paddle oraz zapoznać się z dziennikiem dostarczania serwisu Paddle, aby sprawdzić otrzymaną odpowiedź. Kod 404 oznacza nieprawidłowy lub usunięty webhook, a kod 429 oznacza przekroczenie limitu wywołań przewidzianego w Państwa planie - proszę zapoznać się z sekcją Plany i sposób użytkowania.
Proces jest uruchamiany dla niewłaściwych zdarzeń
Każdy webhook w Państwa sklepie uruchamia ten sam wyzwalacz w Shopify Flow. Proszę dodać warunek oparty na identyfikatorze webhooka jako pierwszy krok przepływu pracy lub zawęzić zakres zdarzeń wysyłanych z Paddle.
Żądania kończą się niepowodzeniem z komunikatem „znacznik czasu wykracza poza dopuszczalny zakres”
Paddle podpisuje zdarzenie sygnaturą czasową, a aplikacja odrzuca wszystkie zdarzenia starsze niż 5 minut. Zazwyczaj wynika to z problemu z zegarem po stronie wysyłającej lub z faktu, że Paddle ponowiło wysyłanie znacznie później, zachowując pierwotną sygnaturę czasową. Ponowne próby wysłania tego samego pierwotnego żądania nie mogą zostać zaakceptowane; proszę poprosić Paddle o wysłanie nowego zdarzenia.
Powiązane
- Weryfikacja podpisanych webhooków - każdy dostawca, którego weryfikujemy, oraz sposób opisania dostawcy, którego nie weryfikujemy.
- Mapowanie danych użytkowych i zmienne w Shopify Flow - pobieranie odpowiednich pól z danych przesyłanych i wprowadzanie ich do Shopify Flow.
- Ochrona przed podwójną dostawą - co się dzieje, gdy Paddle ponawia próbę dostawy.
- Historia i rozwiązywanie problemów - dziennik wszystkich żądań wraz z możliwością odtworzenia.