Kiedy webhook jest lepszy niż odpytywanie API
Integracja może co minutę pytać API, czy coś się zmieniło. Przy kilkudziesięciu awizacjach dziennie prawie każde takie zapytanie kończy się odpowiedzią „nic nowego”. Webhook odwraca kierunek. AwizoSlot sam wysyła zapytanie POST, czyli wiadomość z danymi w formacie JSON, na adres, który podasz, gdy przy awizacji coś się wydarzy.
Przykład z rampy: przewoźnik przesuwa w portalu dostawę z 8:00 na 11:00. WMS dostaje nowy termin bez ręcznego przepisywania i może przesunąć przygotowanie miejsca na towar. Inne scenariusze łączenia systemów opisujemy w artykule integracja systemu awizacji z WMS i ERP.
Jakie zdarzenia wysyła webhook
- appointment.created: utworzono awizację,
- appointment.updated: zmieniono dane, termin lub bramę,
- appointment.status_changed: zmieniono status, a w danych jest status poprzedni i nowy,
- appointment.cancelled: anulowano awizację.
Przy dodawaniu webhooka zaznaczasz, które zdarzenia mają trafiać pod dany adres. Nie ma znaczenia, skąd przyszła zmiana: z panelu magazynu, z portalu przewoźnika czy z API. Wyjątkiem jest automatyczne oznaczenie spóźnienia po przekroczeniu tolerancji, bo ta zmiana statusu nie wysyła webhooka.
Co jest w wiadomości
Każda wiadomość to JSON z czterema polami: event (nazwa zdarzenia), tenant_slug (ścieżka firmy w AwizoSlot), created_at (czas zdarzenia) i data (dane awizacji, m.in. identyfikator, lokalizacja, brama, data i godziny, status, typ operacji, towar, liczba palet i numery zamówień). Nazwa zdarzenia jest też w nagłówku X-AwizoSlot-Event, więc Twój system może rozdzielić wiadomości bez czytania treści.
Jak sprawdzić, że wiadomość przyszła z AwizoSlot
Przy dodaniu webhooka system generuje sekret, czyli tajny klucz do podpisywania wiadomości. Pokazuje się tylko raz, więc od razu zapisz go w konfiguracji swojego systemu. Każda wiadomość jest podpisana tym sekretem algorytmem HMAC-SHA256, a podpis trafia do nagłówka X-AwizoSlot-Signature w postaci sha256= i ciągu znaków. Twój system liczy ten sam podpis z otrzymanej treści i sekretu. Jeśli wynik się nie zgadza, odrzuca wiadomość. Bez tej kontroli każdy, kto pozna adres, mógłby podesłać fałszywe zdarzenie.
Adres webhooka musi zaczynać się od https://. Adresy w sieci lokalnej i localhost są blokowane, więc serwer odbierający musi być dostępny z internetu.
Co się dzieje, gdy Twój serwer nie odpowiada
Wysyłka jest udana, gdy Twój serwer odpowie kodem z grupy 2xx (np. 200) w ciągu 15 sekund. W innym przypadku AwizoSlot ponawia ją po 2, 4, 8 i 16 minutach. Po piątej nieudanej próbie wiadomość zostaje oznaczona jako niedostarczona i nie wraca do kolejki.
Ta sama wiadomość może czasem przyjść dwa razy, np. gdy Twój serwer zapisał dane, ale nie zdążył odpowiedzieć. Odbiorca powinien więc rozpoznawać powtórki, np. po identyfikatorze awizacji, nazwie zdarzenia i polu created_at. Wiadomości wychodzą z kolejki, dlatego mogą dotrzeć chwilę po zmianie w panelu, a nie w tej samej sekundzie.
W których planach są webhooki
Webhooki są w planach Standard, Sieć i Enterprise, tak samo jak API. W planach Test i Start nie da się ich dodać. Jeśli firma przejdzie na plan bez webhooków, AwizoSlot przestaje wysyłać zdarzenia. Dodanie i usunięcie webhooka trzeba potwierdzić hasłem. Ceny planów są w cenniku, a zasady korzystania z integracji w regulaminie API.
Najczęstsze pytania
Czy webhooki działają w planie Start?
Nie. Webhooki są w planach Standard, Sieć i Enterprise. W planach Start i Test nie ma ani webhooków, ani API.
Ile razy AwizoSlot ponawia nieudaną wysyłkę?
Łącznie jest pięć prób: pierwsza i cztery ponowienia po 2, 4, 8 i 16 minutach. Potem wiadomość zostaje oznaczona jako niedostarczona.
Czy webhook przyjdzie, gdy przewoźnik zmieni awizację w portalu?
Tak. Zmiany z portalu partnera, z panelu magazynu i z API wysyłają te same zdarzenia.
Czy mogę odbierać webhooki na adresie http?
Nie. Adres musi używać HTTPS i być dostępny z internetu.
Skąd te zrzuty ekranu
Zrzuty pochodzą z działającej instalacji AwizoSlot, z firmy demonstracyjnej „Firma testowa AwizoSlot”. Adresy webhooków i nazwy na obrazkach są fikcyjne.