Haki na automatyzację - czyli webhook i mailhook

Webhooki i mailhooki pozwalają uruchamiać automatyzację wtedy, gdy wydarzy się coś konkretnego, na przykład zostanie wysłany formularz, zmieni się status płatności albo na specjalny adres przyjdzie wiadomość. Dzięki temu proces nie musi co kilka minut sprawdzać wszystkich systemów.

Sam adres odbierający dane jest prosty. Trzeba jeszcze sprawdzić, czy zdarzenie pochodzi z właściwego źródła, nie zostało zmienione i nie uruchomi procesu kilka razy.

Co to jest webhook?

Webhook można porównać do dzwonka do drzwi. Kiedy ktoś naciska przycisk, od razu wiesz, że coś się wydarzyło. W integracji aplikacja wysyła żądanie HTTP na przygotowany adres i dołącza dane zdarzenia, na przykład identyfikator zamówienia oraz nowy status płatności.

Odbiorca powinien szybko sprawdzić żądanie, zapisać zdarzenie i zwrócić poprawną odpowiedź. Dłuższe działania, takie jak analiza dokumentu lub generowanie raportu, lepiej wykonać później w kolejce. Nadawca może uznać zbyt wolną odpowiedź za błąd i ponowić dostarczenie.

Webhook może też działać jako przycisk uruchamiający proces. Skrót na telefonie lub akcja w bazie danych wysyła żądanie, które rozpoczyna przygotowanie raportu. W takim przypadku mechanizm autoryzacji nadal jest potrzebny, ponieważ poznanie adresu nie powinno wystarczać do wykonania operacji.

Webhook i regularne sprawdzanie zmian

Bez webhooka automatyzacja może co kilka minut pytać API: „czy pojawiło się coś nowego?”. To podejście nazywa się pollingiem. Bywa potrzebne, gdy aplikacja nie wysyła zdarzeń albo webhooki nie obejmują danego typu zmiany.

Webhook zwykle zmniejsza opóźnienie i liczbę zapytań. Polling może pełnić rolę kontroli, która raz na jakiś czas sprawdza, czy żadne zdarzenie nie zostało pominięte. Przy ważnym procesie połączenie obu mechanizmów daje rozsądne zabezpieczenie.

Dostarczenie może nastąpić więcej niż raz

Nadawca często ponawia webhook, gdy otrzyma timeout lub odpowiedź oznaczającą błąd. Może też umożliwiać ręczne ponowne wysłanie zdarzenia. Dokumentacja GitHuba pokazuje oba mechanizmy: ponawianie dostarczeń oraz identyfikator konkretnej dostawy.

Odbiorca powinien zapisać identyfikator zdarzenia przed wykonaniem działań. Jeżeli ten sam identyfikator pojawi się kolejny raz, może zwrócić sukces bez ponownego utworzenia faktury, kontaktu czy płatności. To jest idempotencja w praktyce.

Brak identyfikatora po stronie nadawcy utrudnia sprawę. Można wtedy zbudować własny klucz z typu zdarzenia i identyfikatora obiektu, ale trzeba uwzględnić prawdziwe kolejne zmiany tego samego obiektu. W ważnych procesach warto sprawdzić ten element jeszcze przed wyborem dostawcy.

Kolejność również nie zawsze jest gwarantowana. Zdarzenie „zamówienie wysłane” może dotrzeć przed wcześniejszym „zamówienie opłacone”. Dlatego proces powinien sprawdzić aktualny stan obiektu albo porównać wersję i czas zdarzenia.

Jak zabezpieczyć webhook

Losowy, długi adres utrudnia przypadkowe wywołanie, ale nie daje wystarczającego potwierdzenia nadawcy. Popularnym rozwiązaniem jest podpis kryptograficzny. Nadawca oblicza podpis z surowej treści żądania i wspólnego sekretu, a odbiorca wylicza go ponownie i porównuje wartości.

GitHub zaleca weryfikację podpisu przed przetwarzaniem dostawy. Sekret trzeba przechowywać poza kodem i treścią scenariusza. Porównanie podpisów powinno być odporne na analizę czasu wykonania, a do obliczeń należy użyć niezmienionego body żądania.

Warto również:

• przyjmować wyłącznie połączenia HTTPS,
• sprawdzać typ i rozmiar danych,
• odrzucać zdarzenia ze zbyt starym znacznikiem czasu,
• ograniczyć liczbę żądań,
• rotować sekret i prowadzić historię dostaw,
• usuwać dane wrażliwe z logów.

Filtr adresów IP może być dodatkową ochroną, jeżeli dostawca publikuje aktualny zakres. Nie zastępuje podpisu, ponieważ adresy mogą się zmieniać, a infrastruktura pośrednia komplikuje ich weryfikację.

Co to jest mailhook?

Mailhook uruchamia proces po otrzymaniu wiadomości na specjalny adres. Narzędzie udostępnia skrzynkę lub unikalny adres, a automatyzacja odczytuje nadawcę, temat, treść i załączniki.

Ten mechanizm przydaje się, gdy starszy system potrafi wysłać e-mail, ale nie ma API ani webhooków. Może także zbierać dokumenty od dostawców lub przekazywać powiadomienia do rejestru.

E-mail jest mniej przewidywalnym źródłem danych niż API. Wiadomości mogą się opóźniać, trafić kilka razy, mieć różne kodowanie i format załączników. Pole nadawcy widoczne w wiadomości nie jest wystarczającym dowodem pochodzenia.

Bezpieczne przetwarzanie wiadomości i załączników

Automatyzacja odbierająca pocztę powinna ograniczać typ i rozmiar załączników, skanować pliki oraz przechowywać oryginalną wiadomość z jej identyfikatorem. Pozwala to uniknąć ponownego przetworzenia i wrócić do źródła po błędzie.

Jeżeli dokument jest analizowany przez OCR albo model AI, wynik wymaga walidacji. Numer NIP powinien mieć poprawny format, suma pozycji powinna zgadzać się z kwotą dokumentu, a niejasne przypadki powinny trafić do człowieka. Tekst wiadomości i załącznika należy traktować jako dane. Może zawierać instrukcje próbujące wpłynąć na model lub proces.

Mailhook sprawdza się jako wejście do kolejki dokumentów. Ryzykowne jest automatyczne wykonanie płatności, zmiana rachunku kontrahenta lub nadanie dostępu wyłącznie na podstawie treści e-maila.

Obsługa błędów

Po odebraniu webhooka lub mailhooka warto rozdzielić przyjęcie zdarzenia od wykonania całego procesu. Zapis zdarzenia w kolejce pozwala ponawiać poszczególne kroki, ograniczać tempo i analizować błędy bez proszenia nadawcy o kolejną wiadomość.

Błędy chwilowe mogą być ponawiane z rosnącym odstępem. Błąd danych powinien trafić do osobnej kolejki wraz z powodem odrzucenia. Po poprawieniu problemu operator może ponowić konkretną operację. Historia powinna pokazać, ile było prób i które działania zdążyły się wykonać.

Webhook i mailhook pozostają prostymi sposobami uruchamiania automatyzacji. Ich niezawodność zależy od kilku mało efektownych elementów: podpisu, identyfikatora zdarzenia, kolejki, walidacji i czytelnej obsługi błędów. To one sprawiają, że scenariusz działa także po timeoutcie, duplikacie i nietypowej wiadomości.