Co to jest webhook?

Jak webhook uruchamia agenta

1. ZdarzenieKlient wysyła na stronie formularz z zapytaniem o wycenę.
2. PowiadomienieFormularz od razu wysyła dane zapytania na adres agenta.
3. WeryfikacjaAgent sprawdza podpis, czyli czy powiadomienie naprawdę przyszło z formularza firmy.
4. DziałanieAgent zakłada kartę w CRM i przygotowuje szkic odpowiedzi do akceptacji.

Webhook a API: czym się różnią?

Przy zwykłym API program sam pyta system o dane. Jeśli chce wiedzieć o nowych zamówieniach, musi pytać co kilka minut, czyli stosować odpytywanie (ang. polling). Webhook odwraca kierunek: odbiorca raz rejestruje swój adres, a system sam wysyła powiadomienie, gdy zajdzie zdarzenie. Dokumentacja GitHuba opisuje to jako dane dostarczane w chwili zdarzenia, w przeciwieństwie do odpytywania API. W praktyce oba mechanizmy się uzupełniają: webhook mówi „coś się stało”, a po szczegóły agent często sięga przez API.

Jak działa webhook krok po kroku?

1. Odbiorca, np. agent AI, udostępnia adres internetowy, pod którym czeka na powiadomienia.
2. W systemie źródłowym, np. w sklepie, podaje się ten adres i wybiera zdarzenia: nowe zamówienie, zwrot, zmiana stanu.
3. Gdy zdarzenie zajdzie, system wysyła na ten adres żądanie HTTP z danymi o zdarzeniu.
4. Odbiorca szybko potwierdza odbiór, a dłuższą pracę wykonuje już po potwierdzeniu, bo system źródłowy czeka na odpowiedź tylko krótko.

Jak zabezpieczyć webhook?

• Sprawdzanie podpisu: wiele systemów podpisuje powiadomienia tajnym kluczem. Shopify dodaje podpis HMAC w nagłówku, który odbiorca powinien zweryfikować, zanim cokolwiek zrobi.
• Odporność na duplikaty: to samo powiadomienie może przyjść dwa razy. Shopify zaleca pomijanie powtórek po identyfikatorze powiadomienia.
• Okresowe uzgadnianie danych: dostarczenie webhooka nie zawsze jest gwarantowane, dlatego Shopify radzi nie polegać wyłącznie na nich i co jakiś czas sprawdzać dane przez API.
• Treść jako dane: tekst z formularza pochodzi od klienta i nie może być traktowany jak polecenie dla agenta (prompt injection).

Adres odbiorcy i klucz do podpisu warto traktować jak hasło: trzymać je w menedżerze sekretów i nie umieszczać w kodzie strony.

Gdzie spotyka się webhooki?

W formularzach na stronach, sklepach internetowych, systemach płatności, kalendarzach rezerwacji i narzędziach no-code. Shopify wysyła webhooki m.in. przy zamówieniach i zmianach produktów. Nie każdy system je ma: część udostępnia zamiast tego dziennik zdarzeń, który program przegląda przez API.

Webhooki w naszych agentach

Webhook pozwala agentowi zareagować od razu po zdarzeniu, a nie przy następnym sprawdzeniu skrzynki. Tak działa demo z zapytaniem z formularza: wysłanie formularza uruchamia agenta, który zakłada kartę klienta i przygotowuje szkic odpowiedzi do akceptacji. Gdy system nie ma webhooków, agent sprawdza zmiany przez API w ustalonych odstępach.

Najczęstsze pytania

Czy webhook to to samo co API?

Nie do końca. API to interfejs, z którego program sam pobiera dane, a webhook to powiadomienie wysyłane przez system z własnej inicjatywy, gdy coś się wydarzy. Webhooki są często częścią API danego systemu.

Co się dzieje, gdy odbiorca webhooka jest niedostępny?

Wiele systemów ponawia wysyłkę przez jakiś czas, ale zasady różnią się między dostawcami, a dostarczenie nie zawsze jest gwarantowane. Dlatego webhooki warto uzupełnić okresowym sprawdzaniem danych przez API.

Czy do odbierania webhooków potrzebny jest własny serwer?

Potrzebny jest adres w internecie, który przyjmie powiadomienie. Może to być mała funkcja w chmurze albo usługa platformy no-code, bez utrzymywania własnej maszyny.

Źródła

• GitHub Docs: About webhooks
• Shopify Dev Docs: About webhooks