Programista Next.js w Gdańsku

Programista Next.js dla firm z Gdańska. Route handlery dla webhooków z systemów płatności, ERP i CMS: weryfikacja podpisu, idempotentność, ponowienia. Pracuję zdalnie, umowa B2B.

Programista Next.js

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

Mój profil na WordPress.org

#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(), nie request.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

KrokCo sprawdzić
MetodaTylko POST, reszta dostaje 405
Treśćrequest.text(), bez parsowania przed podpisem
PodpisHMAC z sekretu endpointu, porównanie w stałym czasie
ŚwieżośćZnacznik czasu w granicach tolerancji, nigdy zero
DuplikatyIdentyfikator zdarzenia w bazie, ograniczenie unikalności
Odpowiedź2xx przed ciężką pracą, błąd tylko gdy zapis się nie powiódł
Praca po odpowiedziafter dla krótkich zadań, kolejka dla długich
LogiBez sekretów i bez danych osobowych w komunikatach błędów
TestZdarzenie 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.

Długi Targ w Gdańsku nocą

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

#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.

Zobacz też w innych miastach Polski

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 WP

Potrzebujesz usługi: Programista Next.js w Gdańsku?

Opisz projekt mailem. Odpowiadam w ciągu 48 godzin.

Opisz projekt

Sprawdź inne usługi WordPress i bazę wiedzy