Webhook
Webhook to automatyczne powiadomienie, które jeden system wysyła do drugiego w chwili, gdy coś się w nim wydarzy - na przykład klient opłacił zamówienie albo podpisał umowę. Technicznie to żądanie HTTP POST z danymi zdarzenia, zwykle w formacie JSON, wysyłane na adres URL wskazany wcześniej przez odbiorcę.
Jak działa webhook krok po kroku
Webhook odwraca zwykły kierunek integracji: nie pytasz systemu, czy coś się zmieniło, tylko system sam daje znać. Działa to w czterech krokach. Odbiorca, na przykład system obiegu dokumentów, udostępnia adres URL, pod którym czeka na wiadomości. Administrator wpisuje ten adres w ustawieniach systemu źródłowego i wybiera zdarzenia, które go interesują: nowe zamówienie, opłacona faktura, podpisany dokument. Gdy zdarzenie nastąpi, system źródłowy wysyła na ten adres żądanie HTTP z opisem zdarzenia w formacie JSON, czyli tekstowym zapisie pól i wartości. Odbiorca potwierdza odbiór kodem odpowiedzi z grupy 2xx, najczęściej 200, i uruchamia własne działanie - zakłada sprawę, zmienia status, powiadamia pracownika. Dlatego webhook bywa nazywany odwrotnym API albo wywołaniem zwrotnym (callback).
Webhook a API - czym się różnią
Klasyczne REST API działa na żądanie: program odbiorcy co kilka minut pyta serwer, czy są nowe dane. To tak zwane odpytywanie (polling). Większość zapytań wraca pusta, a zmiana dociera z opóźnieniem równym odstępowi między zapytaniami. Webhook działa na zdarzenie: wiadomość przychodzi od razu i tylko wtedy, gdy jest o czym informować. W praktyce jedno uzupełnia drugie. Webhook często przenosi tylko identyfikator i typ zdarzenia, a po pełne dane - treść dokumentu, pozycje faktury - odbiorca sięga przez API. Nie każdy system oferuje webhooki. Krajowy System e-Faktur ich nie ma: podręcznik KSeF 2.0 wprost mówi, że system nie wysyła powiadomień o nowej fakturze, a program podatnika musi sam odpytywać KSeF.
Jak zabezpieczyć webhook
Adres webhooka jest dostępny z internetu, więc każdy, kto go pozna, może próbować wysłać fałszywe zdarzenie, na przykład „faktura opłacona”. Podstawowe zabezpieczenia to:
- HTTPS - szyfrowane połączenie, bez wyjątków.
- Podpis HMAC - nadawca podpisuje treść wspólnym sekretem, a odbiorca sprawdza podpis przed przetworzeniem wiadomości.
- Identyfikator zdarzenia - pozwala odrzucić duplikaty i powtórzone wiadomości.
- Weryfikacja przez API - przy zdarzeniach finansowych odbiorca potwierdza stan u źródła, zamiast ufać samej treści powiadomienia.
Webhooki w obiegu dokumentów i w rozwiązaniach e-MSI
W obiegu dokumentów webhook jest najkrótszą drogą od zdarzenia w innym systemie do zadania dla pracownika. Sklep internetowy zgłasza zwrot i od razu powstaje sprawa reklamacyjna. Platforma podpisu zgłasza, że kontrahent podpisał umowę, i proces przechodzi do archiwizacji. W drugą stronę system obiegu może sam wysłać webhook, gdy faktura zostanie zaakceptowana, żeby ERP lub komunikator zespołu dowiedział się o tym bez opóźnienia.
Platforma JobRouter®, na której e-MSI buduje procesy, pozwala uruchamiać procesy na podstawie wiadomości e-mail, formularzy i zdarzeń systemowych, a integracje prowadzi przez API i webserwisy, moduły dedykowane oraz własne skrypty. Procesy mogą być też inicjowane z innych aplikacji, a JobRouter® Cloud łączy się z Zapierem, czyli platformą iPaaS, która przekazuje zdarzenia z aplikacji chmurowych. Tam, gdzie źródło nie wysyła powiadomień, jak KSeF, dane trzeba pobierać według harmonogramu - JobRouter® pozwala uruchamiać procesy także o zaplanowanych porach. Więcej na stronie integracja JobRouter.
Najczęstsze błędy przy webhookach
- Brak weryfikacji podpisu - odbiorca przyjmuje wszystko, co trafi na adres.
- Długie przetwarzanie przed odpowiedzią. Nadawca czeka zwykle kilka sekund, potem uznaje wysyłkę za nieudaną i ponawia ją.
- Brak odporności na duplikaty - to samo zdarzenie dwa razy tworzy dwie sprawy lub dwa przelewy.
- Założenie, że zdarzenia przyjdą w kolejności, w jakiej powstały.
- Brak dziennika odebranych wiadomości i monitoringu, przez co awaria wychodzi na jaw po tygodniu.
- Adres webhooka z sekretem w treści URL, przesłany mailem i zapisany w dokumentacji.
Przykłady zastosowania
Klient opłaca zamówienie w sklepie internetowym. Operator płatności wysyła webhook do systemu sprzedaży, który od razu zmienia status zamówienia i przekazuje je do magazynu.
Kontrahent podpisuje umowę na zewnętrznej platformie podpisu. Platforma wysyła webhook, a proces obiegu umowy zapisuje podpisany plik w archiwum i powiadamia opiekuna umowy.
Po ostatniej akceptacji faktury kosztowej system obiegu wysyła webhook do komunikatora zespołu księgowości z informacją, że dokument czeka na zaksięgowanie.
Dział IT chce reagować na nowe faktury zakupowe. KSeF nie wysyła powiadomień, więc proces co kilkanaście minut odpytuje API KSeF i dla każdej nowej faktury uruchamia obieg akceptacji.
Firma kurierska wysyła webhook z informacją, że przesyłka z oryginałem umowy została doręczona, a proces obiegu umowy odnotowuje datę doręczenia i przypomina opiekunowi o terminie zwrotu podpisanego egzemplarza.
Najczęstsze pytania
Co to jest webhook prostymi słowami?
To automatyczna wiadomość, którą jeden program wysyła do drugiego, gdy coś się wydarzy. Zamiast co chwilę sprawdzać, czy przyszło nowe zamówienie, system odbiorcy dostaje informację sam, w chwili zdarzenia. Przypomina to powiadomienie w telefonie zamiast ciągłego odświeżania skrzynki.
Do czego służy webhook?
Webhook służy do natychmiastowego przekazania informacji o zdarzeniu z jednego systemu do drugiego, bez ciągłego odpytywania. Typowe zastosowania to powiadomienie o opłaconym zamówieniu, podpisanej umowie, nowym zgłoszeniu z formularza albo zmianie statusu przesyłki. Odbiorca od razu reaguje, na przykład zakłada sprawę, wysyła wiadomość albo aktualizuje dane.
Czym różni się webhook od API?
API odpowiada na pytania: odbiorca pyta, serwer odpowiada. Webhook działa odwrotnie - serwer sam wysyła wiadomość, gdy nastąpi zdarzenie. API daje pełny dostęp do danych na żądanie, webhook daje natychmiastową informację o zmianie. W integracjach zwykle używa się obu naraz.
Czy webhook jest bezpieczny?
Tak, jeśli odbiorca go poprawnie zabezpieczy: przyjmuje wiadomości tylko przez HTTPS, sprawdza podpis HMAC, odrzuca duplikaty i przy ważnych zdarzeniach potwierdza stan przez API. Niezabezpieczony adres webhooka pozwala każdemu wysłać fałszywe zdarzenie, na przykład informację o opłaconej fakturze.
Co się dzieje, gdy odbiorca webhooka nie działa?
Nadawca nie dostaje potwierdzenia i zwykle ponawia wysyłkę kilka razy w rosnących odstępach czasu. Liczba i czas ponowień zależą od dostawcy. Jeśli awaria trwa dłużej, zdarzenia mogą przepaść, dlatego odbiorca powinien mieć monitoring i sposób na dociągnięcie brakujących danych przez API.
Czy KSeF obsługuje webhooki?
Nie. Podręcznik KSeF 2.0 Ministerstwa Finansów mówi wprost, że KSeF nie wysyła automatycznie powiadomień o otrzymaniu nowej faktury. Program księgowy lub system obiegu faktur musi sam regularnie odpytywać KSeF przez API. Powiadomienia dla pracowników można zbudować dopiero po stronie własnego systemu.
Powiązane hasła
Zobacz, jak wygląda to w systemach, które wdrażamy w polskich firmach.
