Weryfikacja podpisanych webhooków
Workflow Webhooks weryfikuje podpis HMAC webhooka przed uruchomieniem Shopify Flow: 22 wbudowanych dostawców lub własny podpis dla dowolnej usługi.
Wiele usług podpisuje wysyłane przez siebie webhooki, dzięki czemu odbiorca może potwierdzić, że żądanie rzeczywiście pochodziło od nich i nie zostało zmienione w trakcie przesyłania. Proszę ustawić uwierzytelnianie webhooka na HMAC, a aplikacja sprawdzi ten podpis, zanim jakakolwiek informacja dotrze do Shopify Flow. Żądanie, które nie przejdzie tej weryfikacji, zostanie odrzucone z kodem 401 i nigdy nie uruchomi przepływu pracy.
Istnieją dwa sposoby skonfigurowania tej funkcji: można wybrać nadawcę z listy lub opisać sposób, w jaki się on podpisuje.
Wbudowane dostawcy
Wybierz dostawcę w sekcji** Dostawca podpisu** i wklej jego klucz tajny do podpisywania. Aplikacja zweryfikuje następnie zgodność z wytycznymi dostawcy - właściwy nagłówek, kodowanie, podpisaną treść oraz okno odtwarzania - więc nie ma potrzeby konfigurowania niczego więcej. Każdy dostawca posiada własny przewodnik konfiguracji, obejmujący zarówno tworzenie punktu końcowego, jak i budowanie przepływu pracy w Shopify Flow.
W każdym przewodniku podano dokładnie, jakie elementy aplikacja sprawdza w przypadku danego nadawcy oraz gdzie można znaleźć jego klucz podpisujący.
Indywidualny podpis: dowolny inny nadawca
Jeśli nadawca nie znajduje się na liście, proszę wybrać opcję Podpis niestandardowy i opisać sposób podpisywania. Dokumentacja Państwa dostawcy będzie zawierała następujący wpis:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Ten jeden wiersz odpowiada na wszystkie pola:
| Miejsce akcji | Na podstawie przykładu | Co to oznacza |
|---|---|---|
| Nagłówek podpisu | X-Acme-Signature |
Nagłówek zawierający podpis |
| Algorytm | hmac_sha256 |
SHA-256, SHA-1 lub SHA-512 |
| Kodowanie | hex |
hex, base64 lub base64url |
| Podpisany ładunek | {timestamp}.{body} |
Dokładna treść podpisanego dokumentu |
| Sygnatura czasowa | nagłówek, taki jak X-Acme-Timestamp |
Gdzie trafia wartość timestamp |
| Tolerancja powtórki | 300 sekund | Proszę odrzucać wnioski starsze niż ten |
Podpisany ładunek
Proszę wpisać treść podpisu nadawcy, korzystając z poniższych symboli zastępczych:
| Znak zastępczy | Staje się |
|---|---|
{body} |
Nieprzetworzona treść żądania, bajt po bajcie. Wymagane. |
{timestamp} |
Sygnatura czasowa z nagłówka lub nagłówka podpisu |
{url} |
Adres URL tego webhooka, zgodnie z tym, jaki podał Pan/Pani jako nadawca |
{header:name} |
Wartość kolejnego nagłówka żądania |
Typowe formaty: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Proszę skorzystać z** opcji Rozpocznij od dostawcy**, aby skopiować format zbliżony do potrzebnego i zmienić jedynie te elementy, które się różnią.
Miejsce umieszczenia podpisu
- Zwykły: wartością nagłówka jest sygnatura, opcjonalnie poprzedzona wybranym przez Państwa prefiksem, takim jak
sha256=lubv1,. - Klucz = wartość: nagłówek zawiera pary w postaci
t=1700000000,v1=abc.... Proszę podać nazwę klucza zawierającego podpis (v1), opcjonalnie nazwę klucza zawierającego sygnaturę czasową (t) oraz określić, czy pary są oddzielone znakiem,czy;.
Jeśli nagłówek zawiera kilka podpisów oddzielonych spacjami - co zdarza się w przypadku niektórych nadawców podczas zmiany klucza - akceptowany jest każdy z nich, który jest zgodny.
Sekret
Zazwyczaj należy wkleić klucz tajny w takiej postaci, w jakiej przedstawia go nadawca. Niektórzy nadawcy podają klucz zakodowany w formacie Base64 z prefiksem, np. whsec_...: proszę wybrać opcję zakodowany w formacie Base64 i wprowadzić prefiks, który ma zostać usunięty.
Testowanie przed uruchomieniem serwisu
Narzędzie do sprawdzania podpisu znajduje się poniżej ustawień i działa w przypadku niezapisanych zmian.
- Wklej treść i nagłówki rzeczywistego żądania, a następnie naciśnij przycisk Zweryfikuj. Otrzymają Państwo informacje o każdym etapie - znaleziono nagłówek, odczytano podpis, sygnatura czasowa mieści się w zakresie, zbudowano ładunek, porównano podpisy - oraz dokładny tekst, który został podpisany, dzięki czemu w przypadku niezgodności będą Państwo wiedzieć, gdzie wystąpił błąd, a nie otrzymają jedynie informację „nieprawidłowy podpis”.
- Funkcja Generuj poprawny przykład generuje poprawnie podpisane nagłówki oraz gotowe do uruchomienia polecenie
curl, dostosowane do Państwa aktualnych ustawień. Jeśli żądanie to zostanie zaakceptowane, oznacza to, że Państwa konfiguracja jest spójna na całej długości łańcucha.
Tester nigdy nie uruchamia przepływu pracy, nie zapisuje żadnych danych w historii i nie jest wliczany do Państwa planu.
Podpis nie jest zgodny. Co powinienem sprawdzić?
W następującej kolejności: sekret (najczęstsza przyczyna, w tym dodatkowa spacja lub nieprawidłowy klucz środowiska), podpisany ładunek (brakujący znak . lub : między sygnaturą czasową a treścią), kodowanie (hex vs base64) oraz to, czy coś pomiędzy nadawcą a aplikacją spowodowało zmianę treści. Podpisy obejmują surowe bajty, więc serwer proxy, który zmienia format danych JSON, powoduje ich uszkodzenie.
Żądania kończą się niepowodzeniem z komunikatem „znacznik czasu wykracza poza dopuszczalny zakres”
Zegar nadawcy jest niedokładny, żądanie zostało opóźnione lub ponowione z użyciem nieaktualnego znacznika czasu albo jednostka znacznika czasu jest nieprawidłowa. Proszę sprawdzić, czy nadawca stosuje sekundy, milisekundy czy datę w formacie ISO.
Mój nadawca musi najpierw przeprowadzić procedurę weryfikacyjną
Niektóre serwisy (Zoom, Dropbox, Asana, Trello, Notion) wysyłają żądanie weryfikacyjne, na które punkt końcowy musi odpowiedzieć przed dostarczeniem jakichkolwiek zdarzeń; każdy z nich robi to na swój sposób. Z tego powodu nie są one oferowane jako dostawcy obsługujący funkcję „jednym kliknięciem”. Jeśli potrzebują Państwo jednego z nich, prosimy o kontakt z działem pomocy technicznej, podając nazwę nadawcy.
Czy podpis jest gdzieś zapisany?
Nie. Nagłówki podpisów są maskowane w oknie „Historia” oraz w narzędziu „Live Request Inspector”, ponieważ podpis może zostać odtworzony w ramach okna tolerancji.