Webhooki

Webhook jest efektywną i prostą metodą komunikacji pomiędzy aplikacjami. Pozwala na wysyłanie requestów pod ustalony adres URL, bezpośrednio po wykonaniu sformułowanych wcześniej czynności np. złożenie zamówienia, edycja koszyka, po zalogowaniu czy rejestracji nowego klienta. Dzięki temu zintegrowane aplikacje zewnętrzne zostają natychmiast powiadomione o wystąpieniu zmian. Metoda zapewnia sprawne porozumiewanie się pomiędzy sklepem internetowym a zewnętrzną aplikacją, bez wymogu powtarzającego się odpytywania aplikacji.

Przykładem wykorzystania webhooków w sklepie internetowym jest wymiana danych np. z narzędziem do remarketingu, firmą logistyczną, systemem ERP, czy CRM dla e-commerce.

Webhook może zostać wywołany przy zdarzeniach:

• logowanie do sklepu,

• utworzenie konta,

• edycja konta,

• dodanie towaru do koszyka,

• edycja koszyka,

• złożenie zamówienia,

• edycja zamówienia,

• zmiana statusu zamówienia na pakowane,

• zmiana statusu zamówienia na pakowane fulfillment,

• potwierdzenie zamówienia,

• wysłanie zamówienia,

• anulowanie zamówienia,

• zmiana statusu subskrypcji newslettera email,

• zmiana statusu subskrypcji newslettera sms,

• wysyłka zamówienia dropshippingowego,

• usunięcie z zamówienia numeru paczki,

• zmiana statusu zamówienia [Marketplace].

Webhook może zostać wysłany przy użyciu metod:

• POST - do utworzenia zasobu,

• GET - aby uzyskać zasoby,

• PUT - do aktualizacji,

• DELETE - aby usunąć.

Struktura nagłówka Content-Type może być wygenerowana w formatach:

• application/x-www-form-urlencoded,

• application/json,

• text/xml.

Treść requestu oraz parametry GET możesz zaprogramować dowolną zawartością, używając naszego wewnętrznego języka programowania treści. Możesz używać zmiennych z wartościami pętli czy bloków warunkowych.

Webhooki oczekują na odpowiedź z aplikacji zewnętrznej przez 5 sekund. Jeśli po wywołanym zdarzeniu webhook nie doczeka się odpowiedzi potwierdzającej prawidłowy odbiór treści, system ponowi próbę wysyłki webhooka 10 razy w ciągu 3 dni. Pierwsze 3 ponowne próby wysyłki wystąpią co 10 minut, następne podejścia odbędą się w większych interwałach czasowych.

W nagłówku webhooka przekazywany jest token, czyli klucz używany do podpisania webhooka algorytmem SHA-256. Dzięki kluczowi aplikacja zewnętrzna ma pewność, że webhook nie został zmodyfikowany lub uszkodzony podczas swojej internetowej podróży, oraz został wysłany przez autoryzowany sklep. Jeśli przesyłasz w żądaniach wrażliwe informacje takie jak hasła, loginy czy dane personalne, to polecamy wysyłać dane w formie zaszyfrowanej przy użyciu protokołu HTTPS w URL, na jaki zostanie wysłany webhook. W przypadku użycia HTTP webhook przesyłany jest otwartym tekstem.

Webhooki można organizować w kampanie. Dzięki temu w przejrzysty sposób skonfigurujesz nawet dużą ilość skomplikowanych integracji. Pojedyncze webhooki i całe kampanie można eksportować i importować. To doskonałe rozwiązanie dla aplikacji zewnętrznych chcących szybkiej i sprawnej integracji z IdoSell. Dzięki podziałowi na kampanie efektywnie oddzielisz integracje z poszczególnymi aplikacjami. Możesz rozbudować sklep o całkiem nowe funkcjonalności, bez konieczności edycji kodu źródłowego. Wszystko zależy od twojej pomysłowości.

Możesz uzależnić działanie webhooków zgrupowanych na poziomie kampanii (np. dodatkowe parametry przesyłane w treści request'a), od własnych zmiennych konfiguracyjnych, którym użytkownicy w panelu będą mogli nadawać wartości bez konieczności modyfikacji kodu.
Wykorzystując mechanizm eksportu i importu  kampanii, wystarczy zmodyfikować plik ICF, dodając nowy węzeł <setting>.

Przykład:

  <settings>
2
     <setting type="config" name="dodatkowy_par" description="Dodatkowe informacje"></setting>
3
</settings>

Zaimportowanie tak przygotowanego pliku do panelu, będzie skutkowało pojawieniem się w ustawieniach kampanii dodatkowego pola konfiguracyjnego, którego wartość wykorzystasz w kodzie webhooka jako zmienną [config:dodatkowy_par].

W komunikacji poprzez API sklep internetowy jest regularnie odpytywany przez aplikacje zewnętrzne w celu sprawdzenia wystąpienia zmian. Przesyłanie danych na bieżąco wymaga częstych requestów do API, które mogą znacznie obciążać serwer, szczególnie przy większej liczbie integracji. Z kolei rozwiązanie polegające na zmniejszeniu częstotliwości requestów do API, spowoduje opóźnienie aktualizacji danych w aplikacjach zewnętrznych.

Dlatego w IdoSell dostępne jest rozwiązanie w formie webhooków, dzięki którym otrzymujesz informację o wydarzeniu w chwili jego zaistnienia. Możesz produktywniej synchronizować dane bez konieczności zbyt częstego wysłania requestów do API.

FAQ

Czy w URL, na jaki zostanie wysłany webhook oraz w treści wysyłanej w żądaniu, można używać zmiennych?expand_more

Oczywiście można używać zmiennych, a także bloków zdarzeniowych (if) oraz pętli foreach/for. Lista zmiennych możliwych do użycia wraz z opisem znajduje się w edycji webhooka.

Jaki jest czas oczekiwania na wysłanie webhooka do zewnętrznej aplikacji?expand_more

Wywołane webhooki są zbierane w pakiety i wysyłane co 10 minut.

Czy webhook ma timeout oczekiwania na odpowiedź z aplikacji zewnętrznej? Co się stanie, gdy webhook ze sklepu nie doczeka się odpowiedzi z aplikacji zewnętrznej?expand_more

Webhooki przy wysyłce operują zdefiniowanym timeoutem o wartości 5s. Jeśli wystąpi błąd w wysyłce, webhook ponowi wysyłkę 10 razy w ciągu 3 dni. Pierwsze 3 próby wystąpią co 10 minut, 4. próba w ciągu 1 godziny, 5. próba za 6,5 godziny, a 6. próba za 16 godzin. Ostatnie cztery podejścia wystąpią co 12 godzin.

Gdzie znajdę informacje na temat historii wysyłki webhooka?expand_more

Informacje na temat błędów, ostrzeżeń, potwierdzeń wysyłki i innych szczegółów (treść żądania, treść odpowiedzi, podgląd) dostępne są w sekcji ADMINISTRACJA > Dziennik zdarzeń.

Jak mogę przetestować działanie webhooka?expand_more

Przetestuj swoje webhooki używając np. serwisu RequestBin. Instrukcja znajduje się poniżej:

1. Przejdź do sekcji MARKETING I INTEGRACJE > Webhooks. Dodaj nową kampanię, a następnie dodaj webhooka.

2. Po wywołaniu zdarzenia, w tym przypadku logowanie klienta, webhook wysyła wcześniej zdefiniowaną treść w postaci XML.

W jaki sposób wyliczany jest X-Webhook-Hash?expand_more

Hash webhooka (pozwalający na weryfikację źródła), wyliczany jest jako sklejony ciąg znaków zakodowany algorytmem SHA-256 składający się w kolejności:

• id porządkowe z kolejki webhooków do wysłania,

• id webhooka,

• id kampanii webhooka,

• security key.

Wartości 1-3 przesyłane są jako HTTP Header, natomiast klucz uwierzytelniający (sekret), konfigurowany jest w ustawieniach kampanii webhooks.