Jak połączyć Stripe zShopify Flow
Połącz Stripe z Shopify Flow przez Workflow Webhooks. Webhooki z weryfikacją HMAC uruchamiają przepływy przy płatnościach, zwrotach i sporach.
Stripe to platforma płatnicza. Wysyła ona webhook przy każdej płatności, zwrocie środków, sporze, zmianie subskrypcji oraz zdarzeniu związanym z fakturą na Państwa koncie. Wtyczka Workflow Webhooks przekształca to wywołanie w wyzwalacz Shopify Flow, dzięki czemu Państwa sklep może na nie zareagować: oznaczyć klienta, dodać adnotację do zamówienia, wysłać wewnętrzną wiadomość e-mail, zaktualizować metapole - czyli wykonać każdą czynność, do której umożliwia Shopify Flow.
W niniejszym przewodniku opisano cały proces - Stripe wysyła dane, Workflow Webhooks je odbiera i weryfikuje, a Shopify Flow podejmuje odpowiednie działania - przy czym w każdym żądaniu sprawdzany jest podpis HMAC serwisu Stripe, dzięki czemu wyłącznie Stripe może uruchomić Państwa przepływ pracy.
Co można zbudować
- Proszę oznaczyć klienta Shopify, który dokonał płatności za pośrednictwem kasy Stripe lub linku płatniczego, aby Państwa segmenty były zsynchronizowane.
- Proszę dodać adnotację do zamówienia i powiadomić swój zespół natychmiast po wszczęciu sporu.
- Proszę wysłać wiadomość e-mail do pracowników w przypadku niepowodzenia płatności za subskrypcję, aby ktoś mógł skontaktować się z klientem, zanim ten zrezygnuje z usługi.
Typowe zdarzenia, które należy wysyłać: payment_intent.succeeded, charge.refunded, charge.dispute.created, customer.subscription.deleted, invoice.payment_failed.
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 Stripe z uprawnieniem do tworzenia webhooków.
Krok 1 - Utwórz webhook w sekcji Workflow Webhooks
- Otwórz sekcję Workflow Webhooks → Webhooks → Utwórz webhook i nadaj mu nazwę, którą rozpoznasz w Shopify Flow, na przykład
Stripe events. - W sekcji Uwierzytelnianie proszę wybrać opcję HMAC.
- W sekcji Dostawca podpisu proszę wybrać opcję Stripe. Aplikacja automatycznie wypełni pola „nagłówek”, „algorytm”, „podpisany ładunek” oraz „okno powtórki” - 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 - Proszę dodać punkt końcowy w Stripe
W panelu Stripe przejdź do sekcji Developers → Webhooks, dodaj punkt końcowy z skopiowanym adresem URL, a następnie wybierz zdarzenia, które chcesz wysyłać.
Jak znaleźć swój sekret podpisowy w serwisie Stripe
Klucz tajny do podpisywania webhooków (whsec_...) z panelu Stripe → Programiści → Webhooki.
W dokumentacji serwisu Stripe 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 (Klucz tajny) webhooka w sekcji Workflow Webhooks i zapisz. Od tego momentu każda transakcja Stripe będzie weryfikowana, zanim trafi do Shopify Flow.
Co to sprawdza
| Co | Wartość |
|---|---|
| Nagłówek podpisu | Stripe-Signature |
| Miejsce umieszczenia podpisu | W wartości v1 tego nagłówka, zawierającej pary key=value, oddzielone przecinkami |
| Co zostało podpisane | {timestamp}.{body} |
| Podpis | HMAC-SHA256, zakodowany w systemie szesnastkowym |
| Sygnatura czasowa | Wartość t 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 Stripe (lub skorzystać z opcji Wyślij zdarzenie testowe w sekcji Workflow Webhooks), aby usługa Shopify Flow mogła rozpoznać strukturę Państwa danych.
- Każdy posiadany przez Państwa webhook uruchamia ten sam wyzwalacz w Shopify Flow, dlatego proszę dodać pierwszy warunek oparty na identyfikatorze webhooka, aby ograniczyć ten przepływ pracy wyłącznie do Stripe. 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 Stripe. 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 podaną przyczyną, a Weryfikacja podpisanych webhooków zawiera objaśnienie dotyczące 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 jakikolwiek element między Stripe a aplikacją zmienia treść wiadomości. Podpisy obejmują surowe bajty, więc serwer proxy, który zmienia format JSON, powoduje ich uszkodzenie. 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ą Stripe, czy wprowadzono klucz tajny oraz czy Stripe 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 Stripe oraz zapoznać się z dziennikiem dostarczania Stripe, aby sprawdzić, jaką odpowiedź otrzymał. 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 ze Stripe.
Żądania kończą się niepowodzeniem z komunikatem „znacznik czasu wykracza poza dopuszczalny zakres”
Stripe podpisuje sygnaturę czasową, a aplikacja odrzuca wszelkie dane starsze niż 5 minut. Zazwyczaj jest to problem z zegarem po stronie wysyłającej lub sytuacja, w której Stripe ponowił próbę dostarczenia znacznie później, zachowując pierwotną sygnaturę czasową. Ponowne próby związane z tym samym pierwotnym żądaniem nie mogą zostać zaakceptowane; proszę zwrócić się do Stripe 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 Stripe ponawia próbę realizacji transakcji.
- Historia i rozwiązywanie problemów - dziennik wszystkich żądań wraz z możliwością odtworzenia.