Jak podłączyć standardowe webhooki do serwisu Shopify Flow
Podłącz Standard Webhooks (OpenAI, Supabase Auth Hooks) do Shopify Flow z weryfikacją podpisu HMAC, aby przepływy pracy uruchamiały tylko zaufane zdarzenia.
Standard Webhooks to otwarta specyfikacja służąca do podpisywania webhooków, z której korzystają OpenAI, Supabase Auth Hooks oraz coraz większa liczba usług. Jedno gotowe ustawienie obsługuje je wszystkie. Funkcja 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ć notatkę do zamówienia, wysłać wewnętrzną wiadomość e-mail, zaktualizować metapole - czyli wykonać każdą czynność, do której zdolny jest Shopify Flow.
W niniejszym przewodniku opisano cały proces - Standard Webhooks wysyła, Workflow Webhooks odbiera i weryfikuje, a Shopify Flow wykonuje odpowiednie działania - przy czym w każdym żądaniu sprawdzany jest podpis HMAC Standard Webhooks, dzięki czemu wyłącznie Standard Webhooks może uruchomić Państwa przepływ pracy.
Co można zbudować
- Wykorzystaj webhook OpenAI - zakończone zadanie wsadowe lub kompletną odpowiedź - i spraw, by Shopify Flow podjął odpowiednie działania w Państwa sklepie na podstawie tego wyniku.
- Zareaguj na hook uwierzytelniający Supabase, tak aby rejestracja w Państwa aplikacji powiązała się z odpowiednim klientem w Shopify.
- Odbieraj dane z dowolnej usługi zgodnej ze specyfikacją standardwebhooks.com bez konieczności konfigurowania niestandardowego podpisu.
Typowe zdarzenia do wysłania: dowolne zdarzenie zdefiniowane przez usługę wysyłającą.
Ten sam profil weryfikuje również webhooki z OpenAI oraz Supabase Auth Hooks.
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 usłudze Standard Webhooks z uprawnieniem 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
Standard Webhooks events. - W sekcji Uwierzytelnianie proszę wybrać opcję HMAC.
- W sekcji Dostawca podpisu wybierz opcję Standardowe webhooki. Aplikacja automatycznie wypełni pola dotyczące nagłówka, algorytmu, podpisanej treści oraz okna odtworzenia - nie ma potrzeby konfigurowania niczego więcej.
- 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 sekcji „Standardowe webhooki”
Proszę dodać adres URL jako punkt końcowy w usłudze wysyłającej, a następnie skopiować wyświetlony klucz podpisujący (zaczyna się on od whsec_).
Jak znaleźć swój sekret podpisu dla standardowych webhooków
Sekret podpisywania zaczynający się od „whsec_”. Proszę wkleić go w całości; jeśli jest on wyświetlany w postaci „v1,whsec_...” (Supabase), proszę pominąć początkowe „v1,”.
W dokumentacji serwisu Standard Webhooks poświęconej podpisom 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 zmiany. Od tego momentu każda wiadomość dostarczana przez Standard Webhooks będzie weryfikowana przed dotarciem do Shopify Flow.
Co to sprawdza
| Co | Wartość |
|---|---|
| Nagłówek podpisu | webhook-signature |
| Miejsce umieszczenia podpisu | Wartość nagłówka, po przedrostku v1, |
| Co zostało podpisane | {header:webhook-id}.{timestamp}.{body} |
| Podpis | HMAC-SHA256, zakodowany w formacie base64 |
| Sygnatura czasowa | Nagłówek webhook-timestamp, wyrażony 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 | Przed użyciem należy zdekodować kod Base64. Przed dekodowaniem usuwa się przedrostek whsec_. Proszę wkleić tekst dokładnie tak, jak przedstawił go nadawca. |
W podpisanej treści żądania {body} stanowi surową treść żądania, bajt po bajcie, {timestamp} to powyższy znacznik czasu, a {header:webhook-id} to nagłówek żądania webhook-id.
Żą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 sekcji „Standardowe webhooki” (lub skorzystać z opcji Wyślij test 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 proszę dodać pierwszy warunek oparty na identyfikatorze webhooka, aby ograniczyć ten przepływ pracy wyłącznie do standardowych webhooków. 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 sekcji „Standard Webhooks”. 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 wyjaś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 standardowymi webhookami 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 webhooków pokazuje dokładny tekst, który został podpisany.
Przy każdym żądaniu otrzymuję kod błędu 401
Proszę sprawdzić, czy uwierzytelnianie webhooka jest ustawione na HMAC przy wybranym dostawcy Standard Webhooks, czy wprowadzono klucz tajny oraz czy „Standard Webhooks” wysyła dane na adres URL dokładnie tak, jak pokazuje to aplikacja, łącznie z kodem na końcu.
W historii nie ma żadnych wpisów
Żądanie nigdy nie dotarło. Proszę ponownie sprawdzić adres URL w sekcji „Standard Webhooks” oraz przejrzeć dziennik dostarczania tej sekcji, 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 - zobacz 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 za pomocą standardowych webhooków.
Żądania kończą się niepowodzeniem z komunikatem „znacznik czasu wykracza poza dopuszczalny zakres”
Standard Webhooks podpisuje sygnaturę czasową, a aplikacja odrzuca wszelkie zdarzenia starsze niż 5 minut. Zazwyczaj wynika to z problemu z zegarem po stronie wysyłającej lub z faktu, że Standard Webhooks 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; prosimy zwrócić się do Standard Webhooks 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 usługa Standard Webhooks ponawia próbę dostarczenia.
- Historia i rozwiązywanie problemów - dziennik wszystkich żądań wraz z możliwością odtworzenia.