Webhook czy odpytywanie API — jak wybrać sposób synchronizacji

Zamówienie jest opłacone o 9:12, a magazyn dowiaduje się o 9:40, bo synchronizacja chodzi co pół godziny. Przez te dwadzieścia osiem minut dwie osoby patrzą na dwie różne prawdy, a ktoś sprzedaje towar, którego już nie ma.

Pytanie „webhook czy odpytywanie” brzmi jak wybór technologii, ale rozstrzyga je właściciel: ile kosztuje kwadrans rozjazdu w tym przepływie i co zostaje z rekordu, gdy jedna strona przez ten kwadrans milczy. To jedna z decyzji podejmowanych obok mapy pól, klucza dopasowania i dostępów, które ustalamy przed pierwszą linią kodu integracji.

Ile kosztuje Cię kwadrans rozjazdu

Okno tolerancji wyznacza się dla pojedynczego przepływu, nie dla firmy. Weźmy trzy przepływy firmy handlowej — to scenariusze, nie opis zakończonego wdrożenia. Stan magazynowy w sklepie ma okno liczone w minutach, bo sprzedany brakujący towar wraca jako zwrot i poprawka w księgowości. Opłacone zamówienie — do godziny odcięcia kuriera, po której opóźnienie kosztuje cały dzień dostawy. Zestawienie sprzedaży dla księgowości — dobę.

Dlatego w jednej integracji pracują oba tryby, wybierane osobno dla każdego przepływu — tak jak chatbot podający status zamówienia jest tak świeży jak źródło, z którego czyta. To wciąż warstwa danych; reguła „fakturę powyżej pewnej kwoty akceptuje właściciel” należy do warstwy procesu.

Kto inicjuje połączenie

Webhook to wywołanie, które system źródłowy wykonuje z własnej inicjatywy pod adres wskazany przez Ciebie, w momencie zajścia zdarzenia.

Odpytywanie to zapytanie, które Twoja strona wysyła według harmonogramu, pytając o rekordy zmienione od wcześniej zapisanego znacznika.

Cała różnica sprowadza się do tego, kto inicjuje połączenie i po czyjej stronie leży odpowiedzialność za dostarczenie. Opóźnienie, koszt i sposób psucia się wynikają już z tego rozstrzygnięcia.

Gdzie webhook gubi dane

Awarie obu trybów nie są symetryczne. Webhook jest strzałem w jedną stronę: jeżeli w chwili doręczenia Twój serwer się restartuje albo hosting ma kilkanaście minut przerwy, zdarzenia z tego okna nie ma i nikt Cię o tym nie zawiadomi. Dostawca ponawia próbę przez jakiś czas i przestaje; liczbę prób oraz odstępy sprawdza się w jego dokumentacji, nie zakłada z góry. Najgorszy jest brak śladu po stracie: nie wiesz, czego nie dostałeś. Stąd trwała skrzynka wejściowa: surowy pakiet ląduje w kolejce, zanim ktokolwiek zacznie go rozumieć.

Co przychodzi dwa razy i co nie po kolei

Webhooki działają w modelu „co najmniej raz”, nie „dokładnie raz”, i stąd dwa objawy. Duplikat: przyjmijmy, że obsługa pakietu trwa u Ciebie dwanaście sekund, a dostawca czeka dziesięć — uznaje doręczenie za nieudane i wysyła pakiet ponownie, choć pierwszy przebieg właśnie zapisał rekord — faktura powstaje dwa razy. Kolejność: dwa wywołania o tym samym obiekcie potrafią przyjść odwrotnie, „opłacone” przed „utworzone”, bo pierwsze doręczenie było ponawiane, a drugie poszło od razu; system nadpisuje wtedy nowszy stan starszym.

Obrona jest wspólna: klucz idempotencji, czyli identyfikator, po którym poznajesz, że ten sam dokument już przeszedł — identyfikator zdarzenia albo numer dokumentu — sprawdzany przed zapisem i wsparty ograniczeniem unikalności po stronie bazy. Tak pracuje obieg dokumentów RAN-SIGMA, w którym duplikaty blokowane są na poziomie importu. Przy kolejności dochodzi porównanie wersji: pakiet starszy niż zapis w bazie odpada. A pakiet z samym identyfikatorem wymaga zapytania zwrotnego — dwa webhooki plus dwa zapytania to cztery wywołania na jedno zamówienie.

Publiczny adres, pod który dodzwoni się każdy

Adres, pod który dostawca wysyła pakiet, musi stać otworem — nie schowasz go za logowaniem, bo cudzy system nie umiałby się zalogować. Kto go pozna, może wysłać dowolną treść, a integracja bez weryfikacji przyjmie spreparowaną fakturę tak samo chętnie jak prawdziwą. Dlatego dostawca liczy podpis z treści żądania i wspólnego sekretu (HMAC) i wkłada go w nagłówek, a odbiornik przelicza go u siebie i odrzuca niezgodne, zanim cokolwiek zapisze; sekret trzymamy w zmiennych środowiskowych, nigdy w kodzie. Gdy dostawca nie podpisuje, zostaje długi losowy fragment ścieżki i lista dozwolonych adresów IP. Odpytywanie tej powierzchni nie ma.

Gdzie odpytywanie gubi dane — znacznik, limity i usunięcia

Zacznijmy od przewagi: przebieg, który nie doszedł do skutku, nie gubi niczego, bo następny pyta „co się zmieniło od znacznika”, a nie „co przez ostatnie dziesięć minut”. Konstrukcja stoi jednak na znaczniku, a on wymaga trzech rzeczy naraz. Trzymamy go w bazie albo w magazynie danych platformy, nie w zmiennej scenariusza. Bierzemy go z pola updated_at w odpowiedzi dostawcy, nie z zegara własnego serwera, bo rekordy ze szczeliny między zegarami przepadają bezgłośnie. I przesuwamy dopiero po zapisaniu wszystkich rekordów, nigdy w połowie paczki.

Dwa pytania zadaje się dostawcy przed wyceną. Czy API pozwala filtrować po dacie modyfikacji — jeśli nie, zostaje pobieranie całości i porównywanie, co przy kilkudziesięciu tysiącach rekordów przestaje mieścić się w cyklu. I co z usunięciami — skasowany rekord nie ma daty zmiany, więc nie pojawi się w odpowiedzi na „co się zmieniło” i zostaje u Ciebie na zawsze. Najkrótszy odstęp wyznacza limit zapytań, a zużywa go więcej niż jedno wywołanie, gdy odpowiedź jest stronicowana.

Rachunek uruchomień

Policzmy na przyjętych liczbach. Cykl co piętnaście minut to 96 uruchomień na dobę i około 2 880 miesięcznie, także w sobotę o czwartej rano, gdy zapytanie wraca puste. Webhook zużywa uruchomienie tylko wtedy, gdy coś się wydarzyło: przy dwustu zamówieniach miesięcznie płacisz za dwieście przebiegów zamiast blisko trzech tysięcy. Przy dużym ruchu rachunek się odwraca, bo jedno odpytanie potrafi przynieść pięćset rekordów w paczce. I odwrotnie: odpytywanie bazy dwustu tysięcy kontrahentów po dwanaście zmienionych dzisiaj zużywa limit na nic. Naliczanie zależy od platformy i planu — porównanie Make.com, n8n i Zapiera pod kątem rozliczania uruchomień pokazuje, że n8n we własnej instalacji operacji nie liczy.

Kiedy nie opłaca się ani jedno, ani drugie

Są trzy sytuacje, w których odradzamy wydawanie pieniędzy na synchronizację. Mały wolumen przy szerokim oknie: kilka zamówień dziennie i doba na przepływ obsłuży cykliczny eksport pliku albo darmowy konektor producenta. Proces czekający i tak na decyzję człowieka raz dziennie — dane obecne w trzy sekundy zamiast w trzy godziny niczego nie skracają, bo wąskim gardłem jest kalendarz osoby, nie łącze. I brak API po drugiej stronie: zostają wtedy drogi zastępcze, od importu CSV po scraping, wolniejsze i wrażliwe na zmiany u dostawcy, więc wyceniane osobno.

Webhook w dzień, przebieg kontrolny w nocy

Tam, gdzie brak rekordu kosztuje pieniądze, odpowiedź na pytanie z tytułu brzmi „oba naraz”, nie „albo — albo”. Webhook prowadzi ruch bieżący, a zaplanowany przebieg — raz na dobę, przy fakturach co godzinę — dobiera wszystko zmienione w minionym oknie i przepuszcza przez ten sam klucz idempotencji, więc zostaje wyłącznie to, co przepadło podczas wdrożenia albo przerwy hostingu. Raport rozbieżności z takiego przebiegu bywa jedynym miejscem, w którym w ogóle widać, że webhook coś zgubił.

Kosztem jest druga ścieżka do utrzymania, więc taki przepływ nie mieści się w widełkach prostej integracji. W obiegu dokumentów RAN-SIGMA trzy kanały wpływu — Gmail OAuth2, KSeF i ręczny upload z OCR — schodzą się w jednej kolejce, więc tryb wpływu przestaje mieć znaczenie dla akceptującego, a bot archiwizacji odkłada plik z maila na Dysku poniżej trzydziestu sekund.

Przed wyceną warto odpowiedzieć sobie na cztery pytania: jakie jest okno tolerancji tego przepływu, czy druga strona wystawia webhooki i dla których zdarzeń, po czym poznajesz ten sam rekord po obu stronach oraz — to rozstrzyga najmocniej — kto zauważy, że jedno zdarzenie przepadło. Dalej zaczyna się automatyzacja procesu decydująca, co dzieje się z rekordem po jego przyjęciu.

Prosta integracja, czyli dwa systemy spięte jednym webhookiem, zaczyna się od 1 500 PLN netto; integracja wielosystemowa — trzy systemy lub więcej z logiką biznesową pośrodku — to 4 000–15 000 PLN netto, po bezpłatnej konsultacji i analizie w 3–5 dni. Jeżeli brak rekordu kosztuje pieniądze, dokładamy nocny przebieg; jeżeli nie — nie dokładamy.

Najczęstsze pytania o webhooki i odpytywanie API

Aktualizacja: 7 września 2026