Co robią webhooki
Webhook subskrybuje konkretne zdarzenie w sklepie. Gdy to zdarzenie nastąpi, Storeep natychmiast wysyła dane zdarzenia na wskazany przez Ciebie adres URL (typ API) lub na podany adres e-mail (typ E-mail). Webhooki są często używane do integracji śledzenia zamówień, synchronizacji z CRM, konwersji platform reklamowych i automatycznych powiadomień.
Aby zarządzać webhookami, przejdź do Ustawienia → Webhooki. Potrzebujesz uprawnienia settings, aby przeglądać lub zmieniać webhooki.
Limity webhooków
- Maksymalnie 20 webhooków na sklep. Próba dodania 21. webhooka zwraca błąd "You have reached the maximum of 20 webhooks per store".
- Lista pokazuje najnowsze webhooki jako pierwsze, stronicowana po 40 na stronę.
Tworzenie webhooka
Kliknij Dodaj nowy webhook, uzupełnij poniższe pola, a następnie kliknij Dodaj.
Aktywuj
Zaznaczone domyślnie. Gdy jest zaznaczone, webhook działa od razu po zapisaniu i pasujące zdarzenia są wysyłane. Odznacz, aby zapisać webhook w stanie wyłączonym, który niczego nie odbiera. Możesz to zmienić w każdej chwili, edytując webhook.
Nazwa
- Wymagane. Maksymalnie 50 znaków.
- Opisowa etykieta widoczna na liście, np. Facebook CAPI order created.
Typ
- API: Storeep wysyła żądanie HTTP POST z danymi zdarzenia na Twój URL.
- E-mail: Storeep wysyła e-mail z danymi zdarzenia na Twój adres.
Zdarzenie
Zdarzenie sklepu, które uruchamia webhook. Dostępne są trzy zdarzenia:
- Session created: utworzono nową sesję odwiedzającego w sklepie.
- Order created: złożono nowe zamówienie.
- Order updated: zmieniono status lub dane istniejącego zamówienia.
Ważne: typ E-mail obsługuje tylko Order created i Order updated. Jeśli wybierzesz E-mail z Session created, webhook zostanie zapisany, ale nigdy nic nie wyśle. Jeśli potrzebujesz zdarzenia sesji, użyj typu API.
Format
Tylko jedna opcja, Json: payload jest wysyłany jako dokument JSON.
URL (tylko typ API)
- Wymagane, gdy typ to API. Maksymalnie 500 znaków.
- Pole pokazuje prefiks
https://, więc wpisz tylko host i ścieżkę, np.api.example.com/events/order. Jeśli wkleisz pełny adreshttps://lubhttp://, prefiks zostanie usunięty przed zapisaniem. - Dynamiczne placeholdery: wstaw dowolne pole z danych zdarzenia do URL-a za pomocą podwójnych nawiasów klamrowych
{{field_name}}. Przykład:example.com/postback?cid={{fbclid}}&payout={{order_total}}. Wartości są kodowane do URL, a placeholder bez wartości zostanie pusty. Dzięki temu możesz wysyłać dane konwersji bezpośrednio do platformy reklamowej bez pośrednika. - Adres jest sprawdzany po usunięciu placeholderów, więc nieprawidłowy URL zwróci "The url you have entered is incorrect".
Adres e-mail (tylko typ E-mail)
- Wymagane, gdy typ to E-mail. Musi być poprawny adres, maksymalnie 127 znaków.
Edycja webhooka
Kliknij dowolny wiersz, aby otworzyć edytor. Każde pole można edytować. Pole URL wypełnia się tylko, gdy zapisany typ to API, a pole e-mail tylko, gdy zapisany typ to E-mail. Kliknij Zapisz, aby zatwierdzić. Zapisanie z odznaczoną opcją Aktywuj wyłącza webhook bez jego usuwania.
Kolumny listy webhooków
- Nazwa: etykieta z datą utworzenia.
- URL / E-mail: miejsce docelowe.
- Typ: API lub E-mail.
- Zdarzenie: Session created, Order created lub Order updated.
- Format: Json.
- Status: Aktywowany lub Dezaktywowany.
Usuwanie webhooka
Zaznacz jeden lub więcej wierszy i kliknij Usuń webhooki. Usunięcie jest trwałe i zatrzymuje wszystkie przyszłe wysyłki dla tej subskrypcji.
Dostarczenie, ponowne próby i e-maile o błędach
Ta sekcja dotyczy webhooków typu API. Webhooki E-mail są wysyłane tylko raz, bez ponownych prób i bez śledzenia błędów.
Zachowanie przy ponownych próbach
- Każde żądanie ma limit czasu 5 sekund. Jeśli cel zwróci błąd 5xx, 429 (limitowanie), lub nie można się połączyć (błąd połączenia), dostarczenie jest traktowane jako tymczasowa awaria i ponawiane.
- Po pierwszej nieudanej próbie Storeep ponawia wysyłkę z narastającym opóźnieniem do 5 prób: około 30s, 60s, 120s, 240s, a potem 480s. Po ostatniej próbie zdarzenie jest porzucane.
- Odpowiedź 4xx inna niż 429 (np. 404 lub 403) jest traktowana jako trwała awaria. Storeep nie ponawia jej, bo błędny lub odrzucający endpoint nie naprawi się sam.
- Gdy masz kilka webhooków na to samo zdarzenie, ponowna próba dotyczy tylko tych, które nie powiodły się wcześniej. Endpointy, które już zwróciły sukces, są pomijane, więc nie otrzymasz duplikatów.
E-mail o awarii
- Storeep liczy kolejne nieudane dostarczenia dla każdego webhooka. Po 5 kolejnych niepowodzeniach właściciel sklepu otrzymuje e-mail o tytule "Action needed: your Storeep webhook is failing" w swoim języku, z nazwą webhooka, miejscem docelowym, zdarzeniem i ostatnim kodem HTTP.
- Otrzymujesz dokładnie jeden e-mail na każdą serię niepowodzeń. Kolejne e-maile nie są wysyłane, dopóki webhook nie zacznie działać ponownie.
- Gdy tylko dostarczenie się powiedzie, licznik błędów resetuje się do zera i powiadomienie zostaje ponownie aktywowane, więc przyszła seria błędów znów może wysłać e-mail.
Wskazówki i pułapki
- Możesz utworzyć kilka webhooków dla tego samego zdarzenia, np. wysłać Order created zarówno do CRM, jak i do platformy reklamowej jako dwa osobne wpisy.
- Jeśli Twój endpoint wymaga autoryzacji, dodaj token w parametrze URL, wpisany na stałe lub przez
{{placeholder}}z danych zdarzenia, albo użyj proxy, które doda autoryzację przed przekazaniem dalej. - Session created uruchamia się dla każdej unikalnej sesji odwiedzającego i może generować duży ruch w popularnych sklepach. Subskrybuj tylko, jeśli Twój endpoint obsłuży taki wolumen i pamiętaj, że działa tylko z typem API.