Uwierzytelnianie

Skopiuj stronę

Zabezpiecz webhooki uruchamiające Shopify Flow tokenem statycznym w nagłówku lub podpisem HMAC SHA-256 dla Stripe, GitHub, Slack i innych serwisów.

Każdy, kto zna adres URL webhooka, może wysłać do niego żądanie, dlatego to właśnie uwierzytelnianie zapobiega uruchamianiu Państwa procesów w Shopify Flow przez osoby postronne. Należy skonfigurować tę opcję dla każdego webhooka z osobna w sekcji Zabezpieczenia danego webhooka.

Trzy metody

Metoda	W jaki sposób dzwoniący potwierdza swoją tożsamość	Proszę z tego skorzystać, gdy
Brak	Nic	Wyłącznie do celów testowych - nigdy w środowisku produkcyjnym
Token statyczny	Stała wartość tajna w nagłówku żądania	Prawie każda integracja (n8n, Make, Zapier, Państwa własny kod)
HMAC SHA-256	Podpis wygenerowany na podstawie żądania oraz wspólnego klucza	Nadawca podpisuje swoje webhooki (Stripe, GitHub, Slack itp.)

Token statyczny

Proszę nacisnąć przycisk „Generuj” w webhooku, aby uzyskać silny, losowy token, lub wkleić własny. Wywołujący wysyła go w nagłówku:

Edytor webhooków: nazwa i uwierzytelnianie po lewej stronie, karta „Endpoint” zawierająca status, adres URL webhooka oraz identyfikator webhooka po prawej stronie, a powyżej opcje „Podgląd na żywo”, „Test” i „Wykorzystanie” — Token statyczny: proszę wybrać sposób przekazania tokenu przez nadawcę, wygenerować lub wkleić token, a następnie skopiować adres URL webhooka z karty „Punkt końcowy”.

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001"}'

Zmiana nazwy nagłówka

Niektóre systemy mogą wysyłać wyłącznie nagłówki, z których już korzystają. Proszę ustawić nazwę nagłówka uwierzytelniającego w sekcji „Ustawienia zaawansowane”, a my odczytamy token z tego nagłówka zamiast z X-Api-Key:

bash

  -H "X-Custom-Auth: your-token"

W nazwach nagłówków nie rozróżnia się wielkości liter. Nazwy zastrzeżone są odrzucane - Host, Authorization, Cookie, X-Forwarded-*, X-Webhook-*, CF-* i podobne. Są one ustalane lub przepisywane przez serwery proxy i sieci CDN, więc token odczytany z jednego z nich mógłby znajdować się pod kontrolą atakującego.

Gdzie przemieszcza się token

Nie każdy nadawca może dodać dowolny nagłówek. W jaki sposób nadawca przekazuje token? W zakładce „Webhook” dostępne są cztery miejsca:

Wybór	Nadawca wysyła	Proszę z tego skorzystać, gdy
W niestandardowym nagłówku	`X-Api-Key: <token>` lub wybrana przez Państwa nazwa nagłówka	Ustawienie domyślne oraz sposób działania większości integracji
Jako token na okaziciela	`Authorization: Bearer <token>`	Narzędzie posiada pole „Bearer” lub „API-token”
Jako nazwa użytkownika i hasło	HTTP Basic - z wybraną przez Państwa nazwą użytkownika oraz tokenem jako hasłem	Narzędzie to obsługuje wyłącznie uwierzytelnianie podstawowe
W adresie URL	`?token=<token>` lub wybrana przez Państwa nazwa parametru	Nadawca może wywołać jedynie zwykły adres URL i nie ma możliwości ustawiania nagłówków

Nazwa nagłówka Authorization została celowo pozostawiona jako zarezerwowana nazwa niestandardowego nagłówka: obsługiwane są metody „Bearer” i „Basic”, a obsługa obu z nich odbywa się automatycznie. Kod stanu 401 w przypadku tych dwóch metod zawiera również nagłówek WWW-Authenticate, ponieważ niektóre klienty HTTP wysyłają dane uwierzytelniające dopiero po otrzymaniu żądania uwierzytelnienia.

Opcja adresu URL jest najsłabszą z czterech - adresy URL trafiają do logów, danych o stronach odsyłających oraz historii przeglądarki - dlatego należy z niej korzystać wyłącznie wtedy, gdy nadawca nie pozostawia Państwu innego wyboru. Aplikacja wyświetla gotowy adres URL zawierający token i maskuje ten parametr wszędzie tam, gdzie zapisuje żądanie.

HMAC SHA-256

Nadawca oblicza podpis żądania przy użyciu wspólnego klucza; my ponownie go obliczamy i porównujemy. Żądanie, które wyciekło, nie może zostać odtworzone ze zmienioną treścią, ponieważ treść żądania nie jest już zgodna z podpisem.

Ustawienia domyślne dostawców

Wybierz dostawcę podpisu w sekcji „Dostawca podpisu”, a my przeprowadzimy weryfikację zgodnie z dokładnym schematem tego dostawcy - nazwą nagłówka, kodowaniem, zakresem podpisu oraz okresem ważności podpisu. Wystarczy wkleić klucz podpisujący z panelu administracyjnego tego dostawcy i gotowe.

Dostępnych jest 22 wbudowanych dostawców, z których każdy posiada własną instrukcję konfiguracji: Calendly, Customer.io, GitHub, Lemon Squeezy, Linear, Mollie, Paddle, Paystack, Razorpay, Sanity, Sendcloud, Sentry, Shopify, Slack, Square, Standardowe webhooki (OpenAI, Supabase), Stripe, Svix (Clerk, Resend), Typeform, Vercel, WooCommerce oraz Zendesk. Jeśli Państwa dostawcy nie ma na liście, prosimy opisać, w jaki sposób dokonuje on autoryzacji przy użyciu niestandardowego schematu.

Pełną listę, opcję niestandardową oraz wbudowane narzędzie do weryfikacji podpisów można znaleźć w sekcji Weryfikacja podpisanych webhooków.

Webhook z uwierzytelnianiem HMAC i usługą Stripe jako dostawcą podpisu, przedstawiający pole „secret podpisu”, opis tego, co jest sprawdzane, oraz kroki konfiguracji usługi Connect Stripe — Podpisujący nadawca, w tym przypadku Stripe: proszę wybrać dostawcę, wkleić jego klucz podpisujący, a edytor wyświetli, co jest zaznaczone i jak to połączyć.

Ogólny algorytm HMAC

Wobec braku gotowego ustawienia ani niestandardowego schematu stosujemy własne rozwiązanie: strona wywołująca wysyła nagłówek X-Signature, zawierający wartość HMAC-SHA256 wartości nagłówków X-Webhook-*, wygenerowaną przy użyciu klucza tajnego do podpisywania.

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Data: value1value2" \
  -H "X-Signature: <hmac-sha256 of the X-Webhook-* values>" \
  -d '{"data":"payload"}'

Jak wygląda odmowa

Nieudane uwierzytelnienie zwraca kod 401 wraz z treścią w formacie JSON zawierającą przyczynę - pełną listę kodów można znaleźć w sekcji Historia i rozwiązywanie problemów. Odrzucone wywołania są nadal widoczne w narzędziu Live Request Inspector podczas edycji webhooka, dzięki czemu można dokładnie sprawdzić, dlaczego dane wywołanie zostało odrzucone.

Zmiana hasła bez przestojów

Zmiana klucza tajnego w jednym kroku oznacza, że każde żądanie podpisane starym kluczem zakończy się niepowodzeniem, dopóki nadawca nie zaktualizuje swoich danych. Rotacja klucza tajnego w ramach webhooka pozwala tego uniknąć: zawiera on drugi ważny klucz tajny, który jest akceptowany równolegle z głównym kluczem - zarówno w przypadku tokenu statycznego, jak i każdego schematu podpisywania.

Wprowadź nowy hasło w polu Drugie prawidłowe hasło i zapisz. Oba hasła są teraz akceptowane.
Proszę przestawić nadawcę na nowy klucz tajny.
Proszę nacisnąć przycisk Promote, co spowoduje przeniesienie go do głównego pola i wyczyszczenie drugiego pola, a następnie zapisać.

Żadne żądanie nie jest odrzucane na żadnym etapie. Drugi klucz tajny jest przechowywany dokładnie tak samo jak klucz główny i nigdy nie jest zwracany przez interfejs API - zwracana jest jedynie informacja, czy został on ustawiony.

Zachowanie tajemnicy

Nasz interfejs API REST ani serwer MCP **nigdy nie **zwracają tokenu na żadnym poziomie dostępu - one Należy zgłaszać jedynie to, czy dana opcja jest ustawiona. Zobacz Interfejs API dla programistów i MCP.
Dane są szyfrowane w stanie spoczynku.
Zmiana ta wchodzi w życie natychmiast, dlatego proszę skorzystać z drugiego tajnego schematu przedstawionego powyżej zamiast nadpisując pole główne.
Historia zapisanych wywołań ukrywa nagłówek uwierzytelniający, dane uwierzytelniające w standardzie Basic oraz token adresu URL, Zatem zrzut ekranu z historii przeglądarki nie ujawnia Państwa tajemnicy.

Dalsze zawężenie zakresu

Uwierzytelnianie potwierdza, że dzwoniący zna hasło. Listy dozwolonych adresów IP ogranicza źródła, z których mogą pochodzić połączenia, i można je łączyć z dowolnym z powyższych trybów.