Webhook: automatyczne powiadomienie między aplikacjami

Webhook jest mechanizmem powiadamiania zdarzeniowego. Konfigurujesz adres endpointu i wybierasz zdarzenia, które Cię interesują. Gdy zdarzenie wystąpi, źródłowa aplikacja wysyła do tego adresu żądanie HTTP, najczęściej POST z danymi w formacie JSON. To różni webhook od zwykłego odpytywania API: zamiast cyklicznie pytać „czy coś się zmieniło?”, system otrzymuje informację w chwili zmiany.

Dla biznesu opartego na wiedzy webhook może uruchamiać konkretną ścieżkę po nowym zapisie, płatności albo formularzu kontaktowym. Przykład: formularz przekazuje dane leada do endpointu, automatyzacja zapisuje je w CRM, przypisuje źródło i tworzy zadanie kwalifikacji. Model AI może potem przygotować szkic odpowiedzi z użyciem firmowego kontekstu, ale nie powinien automatycznie wysyłać jej bez reguł i zatwierdzenia.

Webhook nie zastępuje API. API służy do świadomego pobierania lub zmieniania danych, gdy Twój system inicjuje żądanie. Webhook jest komunikatem „coś się stało”, więc druga strona inicjuje dostarczenie danych. Do niezawodnego procesu często używa się obu: webhook informuje o nowym zamówieniu, a następnie integracja pobiera z API pełne dane potrzebne do obsługi zamówienia.

Najważniejsza zasada bezpieczeństwa to sprawdzenie autentyczności żądania. Adres endpointu jest publiczny, więc nie wolno ufać samemu faktowi, że ktoś wysłał POST. Dostawcy tacy jak GitHub i Stripe opisują podpisy webhooków: serwer odbiorcy weryfikuje podpis z nagłówka na podstawie sekretu oraz surowego body żądania. Sekret trzymaj poza kodem, regularnie rotuj i odrzuć żądanie z niepoprawnym podpisem.

Kolejna pułapka to ponowne dostarczenie. Dostawca może wysłać ten sam event drugi raz, gdy nie dostał odpowiedzi 2xx, wystąpiła awaria sieci albo mechanizm retry działa zgodnie z projektem. Odbiorca musi być idempotentny: zapisać identyfikator zdarzenia i nie tworzyć drugi raz faktury, zadania lub kontaktu dla tego samego eventu. Najpierw szybko potwierdź odbiór, potem przetwarzaj dłuższą pracę w kolejce.

Zanim podłączysz webhook do automatyzacji, przetestuj pełny przepływ na danych testowych: poprawny podpis, zły podpis, brak pola, duplikat i czasową niedostępność systemu docelowego. Loguj identyfikator zdarzenia, czas odbioru, wynik oraz błąd, lecz nie zapisuj niepotrzebnych danych osobowych. Dopiero gdy wiesz, co dzieje się przy błędzie, możesz włączyć prawdziwe zdarzenia sprzedażowe lub komunikacyjne.