Webhook

Dzięki webhookom systemy firmy reagują na siebie od razu: opłacone zamówienie wysyła pliki, nowe zgłoszenie zakłada zadanie i nikt nie musi co godzinę zaglądać do paneli. Źle zbudowany webhook gubi jednak zdarzenia albo przepuszcza fałszywe powiadomienia od kogoś, kto podszywa się pod nadawcę.

Jak to działa?

1. Odbiorca, czyli Twój system, wystawia publiczny adres HTTPS i zgłasza go u nadawcy, wybierając zdarzenia, o których chce wiedzieć. Obie strony znają wspólny sekret do podpisywania wiadomości.
2. Gdy zdarzenie zajdzie, nadawca wysyła na ten adres żądanie HTTP POST z danymi w formacie JSON. Stripe i GitHub dołączają do niego podpis wyliczony z treści wiadomości i sekretu.
3. Odbiorca sprawdza podpis i wiek wiadomości, a potem identyfikator zdarzenia: jeśli już je obsłużył, pomija powtórkę.
4. Odbiorca od razu odpowiada kodem 2xx, a dłuższą pracę wykonuje w tle, bo GitHub czeka na odpowiedź 10 sekund, a Microsoft Graph tylko 3.
5. Gdy odpowiedzi nie ma, nadawca ponawia doręczenie albo je porzuca, zależnie od usługi.

Przykład z praktyki

Na fkdrive.com sprzedajemy playbook przez Stripe. Gdy płatność przejdzie, Stripe wysyła webhook na nasz serwer, a serwer sam wysyła kupującemu pliki, bez naszego udziału. Przed wysyłką serwer sprawdza podpis i odrzuca wiadomości starsze niż 5 minut, zgodnie z domyślnym ustawieniem Stripe. Zapamiętuje też obsłużone zamówienia, żeby ponowione zdarzenie nie wysłało plików drugi raz. Gdy wysyłka się nie uda, serwer odpowiada błędem. Wtedy Stripe ponawia doręczenie, a o to nam chodzi.

Kiedy ma sens, a kiedy nie?

Webhook ma sens, gdy zdarzenie w jednym systemie ma od razu uruchomić pracę w drugim: płatność wysyła pliki, podpisany dokument zmienia status w portalu klienta. Potrzebny jest nadawca, który obsługuje webhooki, i odbiorca z publicznym adresem HTTPS. Przy sprzedaży przez Checkout Stripe wymaga webhooka do realizacji zamówień, bo kupujący nie zawsze wraca na stronę po płatności.

Gdy nadawca nie wysyła webhooków albo komplet danych liczy się bardziej niż szybkość (zestawienie miesięczne, uzgadnianie płatności), zostaje odpytywanie API, czyli regularne pytanie o zmiany. W ten sposób programy księgowe pobierają na przykład nowe faktury przez integrację z KSeF. Często łączy się oba sposoby: webhook daje szybkość, a okresowe odpytanie wyłapuje zdarzenia, które przepadły.

Takie połączenia, także z przepływami w Microsoft 365, budujemy w ramach automatyzacji i integracji. Napisz, co ma się dziać po zdarzeniu w Twoim systemie. Odpowiadamy zwykle w 1–2 dni robocze, a po krótkiej rozmowie dostaniesz plan prac i wycenę.

Opisz swoją integrację

Na co uważać?

• Podszywanie się. Bez sprawdzania podpisu każdy, kto zna adres, może wysłać fałszywe zdarzenie, a Twój system na przykład wyda pliki bez płatności albo nada komuś dostęp. Podpis trzeba sprawdzić na treści w postaci, w jakiej przyszła, zanim program cokolwiek z nią zrobi.
• Powtórzenia i kolejność. To samo zdarzenie może przyjść kilka razy i nie po kolei. Odbiorca zapisuje, które zdarzenia już obsłużył, i każde wykonuje tylko raz; tę cechę nazywa się idempotencją.
• Różne zasady ponowień. Stripe w trybie produkcyjnym ponawia doręczenie do 3 dni, Microsoft Graph do 4 godzin, a GitHub nie ponawia automatycznie. Gdy Twój serwer nie działał dłużej, brakujące zdarzenia trzeba potem pobrać przez API.
• Sekret i adres. Sekret ma być losowy i zmieniany po podejrzeniu wycieku. W Power Automate adres wyzwalacza HTTP może zawierać klucz SAS, który działa jak hasło; po wycieku wygenerujesz go na nowo.
• Dane osobowe. Zdarzenie z płatności niesie dane kupującego: imię i nazwisko, e-mail, dane do faktury. Pełnych treści zdarzeń nie trzymaj w logach dłużej, niż trzeba, a dostęp do logów ogranicz do osób, które ich potrzebują.
• Utrzymanie. Ktoś musi przeglądać nieudane doręczenia (Stripe i GitHub pokazują je w panelu) albo dostawać alarm, gdy adres odbiorcy zwraca błędy.

Pytania i odpowiedzi

Czym webhook różni się od API?

Webhook jest częścią API nadawcy. Przy zwykłym zapytaniu Twój system pyta o dane, a przy webhooku nadawca sam je przysyła, gdy coś się zmieni. Dlatego webhook bywa nazywany „odwrotnym API”.

Czy Power Automate przyjmie webhook?

Tak. Przepływ z wyzwalaczem „When an HTTP request is received” dostaje własny adres i rusza po każdym żądaniu. Nowe przepływy domyślnie przyjmują żądania tylko od użytkowników z Twojej organizacji. Przed budową przepływu sprawdź w projektancie, czy wyzwalacz ma oznaczenie Premium. Jeśli tak, sama licencja Microsoft 365 nie wystarczy.

Zobacz też

• Power Automate
• Integracja z KSeF
• Portal klienta