Jak skonfigurować webhooki w easySales: wysyłaj zamówienia, etykiety i zmiany stanów do swoich systemów
Wysyłaj zdarzenia z easySales, takie jak nowe zamówienia, etykiety, faktury i zmiany stanów magazynowych, do swoich systemów w chwili, gdy się dzieją, i dbaj o to, by subskrypcje działały.
Do czego służą webhooki
Webhook powiadamia inny system w chwili, gdy coś dzieje się w easySales. Gdy wpada zamówienie, powstaje etykieta albo zmienia się stan magazynowy, easySales wysyła szczegóły na wybrany przez Ciebie adres. Dzięki temu Twój ERP, program księgowy lub sklep internetowy może zareagować od razu, zamiast co kilka minut odpytywać easySales.
Otwórz stronę easy-sales.com/webhooks, gdy jesteś zalogowany. Każda pozycja na niej to subskrypcja: jedno zdarzenie wysyłane na jeden adres.
Trzy rzeczy, które warto wiedzieć na start:
- Adres, który odbiera dane, musisz przygotować Ty lub Twój programista. easySales wysyła dane, a system pod tym adresem decyduje, co z nimi zrobić.
- Subskrypcja, która ciągle zawodzi, sama się wyłącza. Po 100 nieudanych próbach easySales przestaje wysyłać dane i powiadamia Cię e-mailem. Subskrypcja nie włącza się ponownie sama.
- Gdy subskrypcja jest wyłączona, zdarzenia nie są przechowywane. Po jej ponownym włączeniu wysyłka rusza od tej chwili.
Jak dodać subskrypcję zdarzenia
- Kliknij Subscribe to webhook.
- W polu Url wpisz adres, który ma odbierać dane. Użyj adresu https.
- W polu HTTP method zostaw POST.
- W polu Webhook wybierz zdarzenie.
- W polu Secret wpisz klucz o długości co najmniej 24 znaków. Twój system sprawdza nim, czy dane naprawdę pochodzą z easySales.
- Kliknij Save.
Subskrypcja pojawi się pod nazwą swojego zdarzenia. Aby wysyłać to samo zdarzenie także do drugiego systemu, dodaj kolejną subskrypcję z innym adresem. Dany adres można dodać tylko raz dla każdego zdarzenia.
| Zdarzenie | Kiedy jest wysyłane |
|---|---|
| Order created | Wpada nowe zamówienie z dowolnego kanału albo zamówienie zostaje dodane ręcznie. |
| Order updated | Na zamówieniu zmienia się cokolwiek, np. status, produkty lub adres. To zdarzenie jest wysyłane często. |
| Awb created | W easySales zostaje utworzona etykieta kurierska do zamówienia. |
| Delivery status updated | Kurier zgłasza nowy status doręczenia przesyłki. |
| Invoice created, Storno invoice created | Do zamówienia zostaje wystawiona faktura lub faktura korygująca. |
| Return created, Return updated | Zostaje utworzony zwrot albo zmieniają się jego status, produkty, notatki, przesyłki lub faktury. |
| Product created, Product updated | Produkt zostaje dodany lub zmieniony, także jego cena. |
| Product stock updated | Zmienia się stan magazynowy produktu. |
| Category created / updated, Characteristic created / updated | Kategoria lub cecha zostaje dodana albo zmieniona. |
| Products refresh requested, Stock refresh requested | Dla sklepu internetowego zostaje zlecone odświeżenie produktów lub stanów magazynowych. |
| Ticket created, Ticket updated | W Klienci → Zgłoszenia zaczyna się rozmowa z kupującym albo istniejąca rozmowa się zmienia. |
| Account suspended, Account activated | Konto easySales zostaje zawieszone lub ponownie aktywowane. |
Sprawdź, co zostało wysłane
Przy każdej subskrypcji widać Success albo Failed dla ostatnio wysłanego zdarzenia oraz czas wysyłki. Kliknij More details..., aby zobaczyć to zdarzenie:
- Payload to dane wysłane przez easySales.
- Response to odpowiedź Twojego adresu wraz z kodem statusu.
- Attempt 2 of 3 | Next attempt: … oznacza, że wysyłka się nie powiodła i zdarzenie zostanie wysłane ponownie. Final attempt has been made oznacza, że dla tego zdarzenia nie będzie już kolejnych prób.
Widać tu tylko ostatnie zdarzenie każdej subskrypcji.
Jak zmienić, wstrzymać lub usunąć subskrypcję
- Edit zmienia adres, metodę HTTP lub klucz. Aby wysyłać inne zdarzenie, zasubskrybuj to zdarzenie i usuń starą subskrypcję.
- Disable wstrzymuje subskrypcję, a Enable ponownie ją uruchamia. W czasie wstrzymania nic nie jest wysyłane, a zdarzenia z tego okresu nie zostaną wysłane później.
- Unsubscribe od razu usuwa subskrypcję.
Co musi robić Twój system
| Szczegóły | |
|---|---|
| Format | JSON, z danymi zdarzenia w payload oraz id subskrypcji i nazwą zdarzenia w webhook. |
| Podpis | Nagłówek Signature zawiera HMAC-SHA256 treści żądania, obliczony Twoim kluczem. Obliczaj go na treści dokładnie w takiej postaci, w jakiej dotarła. |
| Odpowiedź | Dowolny status 2xx w ciągu 3 sekund. Najpierw odpowiedz, a dane przetwórz później. |
| Certyfikat | Adresy https muszą mieć ważny certyfikat. |
| Ponowne próby | Trzy próby na zdarzenie: druga ok. 10 sekund po pierwszej, trzecia ok. 100 sekund później. |
| Kolejność dostarczania | Przez ponowne próby zdarzenia mogą docierać w innej kolejności. Opieraj się na danych z payloadu, a nie na czasie ich dotarcia. |
Gdy subskrypcja sama się wyłączy
Liczy się każda nieudana próba: odpowiedź z błędem, brak odpowiedzi w ciągu 3 sekund lub problem z certyfikatem. Po 100 nieudanych próbach subskrypcja zostaje wyłączona, a Ty dostajesz e-mail „Webhook został deaktywowany”. Przycisk Zobacz webhooki w tej wiadomości otwiera tę stronę.
- Usuń problem po stronie adresu, który odbiera dane.
- Kliknij Enable przy subskrypcji.
- Pobierz przez API easySales zmiany, które Cię ominęły, np. zamówienia zmienione w tym czasie.
Dostęp zespołu do webhooków
Członek zespołu potrzebuje uprawnienia Webhooki, aby otworzyć stronę. Z tym uprawnieniem może dodawać, zmieniać, wstrzymywać i usuwać subskrypcje.
Gdy coś nie działa tak, jak powinno
| Objaw | Co zrobić |
|---|---|
| Nic już nie dociera, a przy subskrypcji widać Enable | Subskrypcja została wyłączona po powtarzających się błędach. Popraw adres, kliknij Enable, a potem pobierz pominięte zmiany przez API. |
| Ostatnie zdarzenie ma status Failed | Otwórz More details... i sprawdź kod statusu oraz odpowiedź swojego adresu. |
| „The secret must be at least 24 characters.” | Wpisz klucz o długości co najmniej 24 znaków. |
| „The url has already been taken.” | Ten adres już otrzymuje to zdarzenie. Zamiast dodawać nową subskrypcję, edytuj istniejącą. |
| Nie docierają faktury korygujące | Zasubskrybuj Storno invoice created; Invoice created obejmuje tylko zwykłe faktury. |
| System odbierający jest zalewany aktualizacjami zamówień | Order updated jest wysyłane przy każdej zmianie. Odpowiadaj szybko, a dane przetwarzaj w tle. |