Moje miejsce w społeczności WordPress
- Konto na wordpress.org mam od 2006 roku.
- Współtworzyłem rdzeń WordPressa w wersjach 7.0 i 7.1.
- Utrzymuję 30 wtyczek na wordpress.org.
- Organizuję WordCampy i występuję na nich jako prelegent.
- Byłem na każdym WordCamp Europe od 2017 do 2026 roku.
- Lokalne spotkania WordPressa: WordUp Trójmiasto
Webhook to endpoint, który ktoś obcy może wywołać
Firmy z Gdańska zwykle zgłaszają się z tym samym zadaniem: płatność, system magazynowy albo CMS ma coś zakomunikować sklepowi lub portalowi, a Next.js ma na to zareagować. Zamówienie ma zmienić status, faktura trafić do ERP, a po edycji w CMS odświeżyć się podstrona. Technicznie to jeden plik, route.ts, ale od jego jakości zależy, czy pieniądze i stany magazynowe zgadzają się z rzeczywistością.
Według dokumentacji route handlerów handler działa na standardowych API Request i Response, obsługuje metody GET, POST, PUT, PATCH, DELETE, HEAD i OPTIONS, a wywołanie nieobsługiwanej metody kończy się odpowiedzią 405. Dokumentacja pokazuje też przykład webhooka: funkcja POST, która czyta treść przez request.text() i przy błędzie zwraca 400. Nie trzeba konfigurować bodyParsera, jak w API Routes starego Pages Routera.
Przewodnik Backend for Frontend przypomina, że route handlery to publiczne endpointy HTTP, dostępne dla każdego klienta. Z tego zdania wynika cała reszta tej strony: skoro każdy może wysłać żądanie, handler musi sam sprawdzić, kto je wysyła.
Podpis: sprawdzaj go na surowej treści
Większość dostawców podpisuje webhook skrótem HMAC. Jako przykład biorę dokumentację Stripe, bo opisuje mechanizm szczegółowo. Inni dostawcy, w tym polskie bramki płatności i systemy ERP, robią to inaczej, więc zawsze czytam ich własną specyfikację.
U Stripe nagłówek Stripe-Signature zawiera znacznik czasu t i jeden lub kilka podpisów v1, czyli HMAC SHA-256 liczony z połączenia znacznika czasu, kropki i niezmienionego ciała żądania. Kilka podpisów v1 pojawia się, gdy trwa wymiana sekretu: stary może działać równolegle nawet do siedmiu dni, więc wystarczy, że pasuje jeden z nich. Podpisy porównuje się funkcją o stałym czasie działania. Potem sprawdza się wiek znacznika czasu: biblioteki Stripe domyślnie tolerują pięć minut, a tolerancja równa zero wyłącza sprawdzanie świeżości, więc nie wolno jej ustawiać.
Po stronie Next.js wynikają z tego dwie reguły:
- Czytaj
request.text(), nierequest.json(). Stripe zaznacza, że wymaga surowej treści i że każda jej zmiana psuje weryfikację. Tekst parsujesz do JSON dopiero po sprawdzeniu podpisu. - Ciało można odczytać tylko raz. Przewodnik Backend for Frontend pokazuje, że drugi odczyt rzuca błąd, a jeśli potrzebujesz dwóch, trzeba użyć
request.clone().
Pomaga też dyscyplina wokół sekretu: osobny sekret na każdy endpoint, trzymany w zmiennych środowiskowych. Dokumentacja Next.js radzi dodatkowo nie zdawać się na samo proxy przy uwierzytelnianiu. Sprawdzenie ma być w handlerze, bo tylko ono wykona się na pewno.
Odpowiedź szybko, praca potem
Dostawca czeka na odpowiedź ograniczony czas. Stripe pisze wprost, że endpoint ma zwrócić 2xx przed jakąkolwiek złożoną logiką, a jako przykład podaje oznaczenie faktury jako opłaconej w systemie księgowym. Wolniejsza odpowiedź to przekroczenie czasu i kolejna próba dostawy.
Next.js daje na to funkcję after. Planuje ona pracę na moment po zakończeniu odpowiedzi, jest stabilna od wersji 15.1.0 i działa w route handlerach. Ma jednak granice. Wykona się tylko w czasie, który pozwala platforma, a długość można podnieść ustawieniem maxDuration, jeśli host to wspiera. W trybie export nie działa w ogóle. Dla zadań, które mogą trwać minuty, lepsza jest kolejka, a handler tylko zapisuje zdarzenie. Stripe też zaleca asynchroniczną kolejkę, bo nagły szczyt zdarzeń potrafi przeciążyć serwer przetwarzający je na bieżąco.
Ponowienia i idempotentność
Dostawca ponawia wysyłkę, gdy odpowiedź nie jest 2xx. Według Stripe w trybie produkcyjnym robi to do trzech dni ze wzrastającymi odstępami, a w piaskownicy trzy razy w ciągu kilku godzin. Odpowiedź 3xx też liczy się jako błąd, więc adres endpointu musi być docelowy, bez przekierowań.
Ponowienie znaczy, że ten sam webhook może dotrzeć dwa razy, a Stripe dodaje, że kolejność zdarzeń nie jest gwarantowana. Znacznik czasu created ma rozdzielczość sekundy, więc nie służy do ustalania kolejności ani do sprawdzania, czy zdarzenie już przetworzono. Zalecenie jest proste: zapisuj identyfikatory przetworzonych zdarzeń i pomijaj te, które już masz. Czasem generowane są też dwa osobne zdarzenia o tym samym skutku, a wtedy do rozpoznania dubla służy identyfikator obiektu z data.object razem z typem zdarzenia.
W Next.js jest tu pułapka sprzętowa. Przewodnik Backend for Frontend ostrzega, że część hostów uruchamia route handlery jako funkcje bezserwerowe. Handlery nie dzielą wtedy danych między żądaniami, środowisko może nie pozwalać na zapis plików, a długo działające handlery bywają przerywane po przekroczeniu czasu. Dlatego rejestr przetworzonych zdarzeń musi leżeć w bazie, nie w zmiennej w pamięci. Ta sama uwaga dotyczy ograniczania liczby żądań: licznik w pamięci liczy każdą instancję osobno i zeruje się po restarcie, więc przy kilku instancjach potrzebny jest wspólny magazyn albo limit po stronie hosta.
Wzorzec, który stosuję: handler weryfikuje podpis, zapisuje w bazie identyfikator zdarzenia z ograniczeniem unikalności, odpowiada 200, a skutki uboczne wykonuje po odpowiedzi. Jeśli zapis się nie uda, zwraca błąd, żeby dostawca spróbował jeszcze raz.
Webhook z CMS: odświeżanie zamiast księgowania
Drugi częsty przypadek to CMS, na przykład headless WordPress, który po publikacji powiadamia front. Przewodnik Backend for Frontend podaje właśnie taki przykład: handler sprawdza token, odczytuje tag i wywołuje revalidateTag, a odpowiedź to JSON z wynikiem. Wynik widać od razu na stronie, a pomyłka kosztuje najwyżej zbędne odświeżenie.
Dokumentacja pokazuje token w adresie URL. Wolę sekret w nagłówku albo podpis ciała, bo adresy trafiają do logów serwera. To moja preferencja, nie wymóg dokumentacji. Warto też pamiętać, że sprawdzenie dostępu w handlerze nie wykona się dla odpowiedzi, które CDN wcześniej zapisał w pamięci podręcznej. Dokumentacja radzi cache’ować tylko to, co bezpiecznie zobaczy każdy, kto zna adres. Handlery POST nie są cache’owane, a od wersji 15 domyślnie nie są nimi także handlery GET.
Lista kontrolna handlera webhooka
| Krok | Co sprawdzić |
|---|---|
| Metoda | Tylko POST, reszta dostaje 405 |
| Treść | request.text(), bez parsowania przed podpisem |
| Podpis | HMAC z sekretu endpointu, porównanie w stałym czasie |
| Świeżość | Znacznik czasu w granicach tolerancji, nigdy zero |
| Duplikaty | Identyfikator zdarzenia w bazie, ograniczenie unikalności |
| Odpowiedź | 2xx przed ciężką pracą, błąd tylko gdy zapis się nie powiódł |
| Praca po odpowiedzi | after dla krótkich zadań, kolejka dla długich |
| Logi | Bez sekretów i bez danych osobowych w komunikatach błędów |
| Test | Zdarzenie powtórzone dwa razy i zdarzenia w odwrotnej kolejności |
Kiedy wystarczy WordPress bez Next.js
Jeśli prowadzisz sklep na WooCommerce ze standardową bramką płatności, ta strona nie jest o tobie. Wtyczka bramki odbiera webhooki sama, a zamówienia obsługujesz w panelu. Dołożenie Next.js oznacza wtedy dodatkowy system do utrzymania bez wyraźnej korzyści. Własny handler ma sens, gdy obieg jest niestandardowy: zdarzenie z ERP ma zmienić stan na froncie, płatność ma uruchomić proces poza sklepem albo front headless potrzebuje powiadomienia z CMS. Po takiej rozmowie często polecam zostać przy tym, co masz.

Zdjęcie: Marcin Białek, CC BY-SA 4.0, Wikimedia Commons.
Praca zdalna z Gdyni dla firm z Trójmiasta
Mieszkam w Gdyni, a projekty prowadzę wyłącznie zdalnie i pisemnie. Dla ciebie oznacza to jasny zapis ustaleń: brief, pytania, zakres i założenia na piśmie, wdrożenie na środowisku testowym, odbiór i opcjonalna opieka po uruchomieniu. Wizualna strona, układ i makiety pochodzą od ciebie, ja wdrażam je w działający interfejs.
Do startu potrzebuję: opisu zdarzeń, które mają przychodzić, dostępu do dokumentacji dostawcy, środowiska testowego albo piaskownicy po stronie dostawcy i informacji, gdzie dziś zapisują się zamówienia. Wszystko inne ustalimy w pytaniach pisemnych.
Powiązane strony
- Programista Astro w Gdańsku, gdy front ma być stroną z treścią, nie aplikacją.
- Programista PHP w Gdańsku, gdy backend zostaje w PHP.
- Programista Shopify w Gdańsku i programista WooCommerce w Gdańsku, gdy sklep ma gotową platformę.
- Migracja między Next.js a Astro w Gdańsku.
Pytania i odpowiedzi
Czy do odbioru webhooka potrzebuję osobnego backendu?
Nie. Route handler w Next.js to zwykły publiczny endpoint HTTP, więc przyjmie webhook z płatności, ERP albo CMS. Osobny serwis ma sens dopiero wtedy, gdy przetwarzanie jest ciężkie albo długie. Wtedy handler tylko przyjmuje zdarzenie, a resztę robi kolejka.
Dlaczego podpis webhooka nie przechodzi, choć sekret jest dobry?
Najczęściej ktoś sparsował ciało żądania przed sprawdzeniem podpisu. Podpis liczy się z dokładnych bajtów, które wysłał dostawca. Przeczytaj treść przez request.text(), zweryfikuj podpis, dopiero potem zamień tekst na JSON.
Co zrobić, żeby ponowiony webhook nie zaksięgował płatności dwa razy?
Zapisuj identyfikator zdarzenia w bazie i pomijaj to, które już widziałeś. Pamięć procesu nie wystarczy, bo część hostingów uruchamia handlery jako osobne funkcje i nie dzielą one danych między żądaniami.
Czy mogę odpowiedzieć dostawcy dopiero po zaksięgowaniu zamówienia?
Lepiej nie. Dostawcy oczekują szybkiej odpowiedzi 2xx, a po przekroczeniu czasu ponawiają wysyłkę. Zapisz zdarzenie, odpowiedz, a księgowanie dokończ po odpowiedzi albo z kolejki.
Kiedy wystarczy sam WordPress z WooCommerce?
Gdy sklep ma standardową bramkę płatności w wtyczce, a zamówienia obsługujesz w panelu. Wtyczka bramki odbiera webhooki sama i nie potrzebujesz do tego Next.js. Własny handler ma sens przy niestandardowym obiegu, na przykład gdy zdarzenie z ERP ma uruchomić odświeżenie treści na froncie.
Jak zaczyna się współpraca?
Piszesz do mnie, jakie systemy mają wysyłać zdarzenia i co ma się po nich stać. Odpowiadam pisemnie w dni robocze, z pytaniami i wstępną wyceną. Pierwsza pisemna wycena jest bezpłatna.
Napisz, co ma przychodzić do twojej aplikacji
Wyślij mi przez formularz kontaktowy adres obecnej strony, listę systemów, które mają wysyłać zdarzenia, termin i obecny stack. Odpowiem pisemnie, z pytaniami i wstępną wyceną. Pierwsza pisemna wycena jest bezpłatna.
Wybrane projekty
Przykłady mojej pracy.
kaminski.pl - Projekt WordPress | WPPoland
Kaminski.pl to witryna stworzona dla podróżnika i blogera Michała Kamińskiego, który dzielił się swoimi doświadczeniami z eksploracji świata, inspirując inny...
kochamruch.pl - Projekt WordPress | WPPoland
Projekt strony kochamruch.pl dla społeczności aktywności fizycznej, oparty na WordPressie i przygotowany pod publikację treści oraz prostą administrację.
Konferencja Technik Szerokopasmowych
Projekt realizowany dla Broadband Technology Conference to prezentuje innowacyjne systemy dla sprzętu aktywnego dostępu oraz cyfrow...
Wsparcie techniczne WordPress w Gdańsku
Najbliższe wydarzenia WordPress
Spotkaj się z nami na WordCampie
Dołącz do społeczności WordPress w Gdańsku. Regularnie bywam na meetupach i WordCampach w całej Polsce - WordUp Trójmiasto, WordCamp Polska i WordCamp Europe. Podejdź i porozmawiajmy.
Dodaj kalendarz WPPotrzebujesz usługi: Programista Next.js w Gdańsku?
Opisz projekt mailem. Odpowiadam w ciągu 48 godzin.
Opisz projektSprawdź inne usługi WordPress i bazę wiedzy
Migracja do Astro, Next.js i headless WordPress.
Synchronizacja WooCommerce z ERP i hurtownią.
Automatyzacja procesów biznesowych wokół WordPress i systemów firmowych.
Biblioteka konkretnych przypadków automatyzacji.
Headless WordPress, Sanity, Strapi i Contentful z Astro lub Next.js.
Astro, MDX, edge i Core Web Vitals mierzone na realnym ruchu.
Dedykowany development i architektura WordPress.
Skalowalna architektura headless, ERP i AI dla enterprise.
Powiązane kategorie
Artykuły wspierające temat

Od sześciu do szesnastu tygodni dla typowych projektów, w czterech fazach: rozpoznanie, ustalanie zakresu, budowa i przełączenie, dostrajanie. Zmiennymi są wielkość katalogu, liczba integracji, zachowanie URL-i i gotowość zespołu redakcyjnego, a nie wybór frameworka.

Kompleksowa 4-letnia analiza całkowitego kosztu posiadania (TCO), laboratoryjne i polowe benchmarki Core Web Vitals, architektura Astro 7 GraphQL APQ oraz 10-punktowa matryca decyzyjna dla organizacji enterprise wybierających między headless a monolitem WordPressa.

Decyzja Shopify Plus vs WooCommerce headless w 2026 nie jest już binarnym wyborem "platforma vs custom". Obie platformy działają w trybie headless, obie integrują AI, obie renderują na edge. Realne osie to kontrola, koszt całkowity przez pięć lat oraz strategia wyjścia. Ten artykuł przechodzi przez macierz decyzyjną z potwierdzonymi faktami platformowymi.