Weryfikacja podpisu webhooka Stripe nie powiodła się — sprawdź dlaczego

Debuguj swój podpis Stripe

Stripe jest wybrany domyślnie. HMAC liczy się w Twojej przeglądarce za pomocą WebCrypto — Twój whsec_ nigdy nie opuszcza karty.

Anatomia nagłówka Stripe-Signature

Każdy webhook Stripe przychodzi z jednym nagłówkiem, który wygląda tak. Każde pole oddzielone przecinkiem ma swoje zadanie:

Stripe-Signature: t=1614556800,
  v1=5257a869e7ecebeda32affa62cdca3fa51cad7414a563a8c6e3c4b41c2b7f2c8,
  v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

Podpisywany ciąg to `${t}.${rawBody}` — nie samo body. Pomiń prefiks t. we własnym weryfikatorze, a każdy podpis zawiedzie, nawet z właściwym sekretem.

6 głównych przyczyn, w kolejności sprawdzania

Uszeregowane według tego, jak często są winowajcą. Każda ma znak rozpoznawczy, który odróżnia ją od pozostałych.

Poprawka surowego body, framework po frameworku

Przyczyna nr 1 to niemal zawsze to: Twój framework webowy odczytał, sparsował i ponownie zserializował JSON, zanim zobaczył go constructEvent. Ponownie zserializowany JSON ma inne białe znaki, więc HMAC przestaje się zgadzać. Oto jak przekazać każdemu frameworkowi nietknięte bajty.

// Trasa webhooka MUSI być przed express.json()
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);
app.use(express.json()); // cała reszta

export async function POST(req: Request) {
  const body = await req.text();            // surowe, nietknięte
  const sig = req.headers.get('stripe-signature')!;
  const event = stripe.webhooks.constructEvent(
    body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

import { buffer } from 'micro';
export const config = { api: { bodyParser: false } };

export default async function handler(req, res) {
  const raw = await buffer(req);
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(
    raw, sig, process.env.STRIPE_WEBHOOK_SECRET
  );
  res.json({ received: true });
}

Wklej dokładne bajty do debuggera powyżej: jeśli podpis zgadza się dopiero po usunięciu końcowego znaku nowej linii albo przekodowanego pola, body zostało zmienione po drodze — a nie Twój sekret.

Tryb testowy a live: sekret, który wygląda dobrze, ale nie jest

Stripe daje Ci trzy różne wartości whsec_ i łatwo je pomylić. Pierwsza to sekret endpointu testowego, widoczny w Dashboardzie w trybie testowym. Druga to sekret endpointu live — osobna wartość tego samego endpointu przełączonego na live. Trzecia to sekret CLI, który wypisuje stripe listen, znowu inny i ważny tylko dla zdarzeń przekazywanych przez tę sesję. Wszystkie trzy dają wiarygodnie wyglądający HMAC, więc błąd jest ten sam, ogólny No signatures found — nic nie mówi o pomyleniu trybów. Znak rozpoznawczy: płatności testowe się weryfikują, prawdziwe dostają 400. Rozwiązanie: odczytaj sekret z dokładnie tego endpointu, w dokładnie tym trybie, który odbiera ruch.

5-minutowe okno ochrony przed replay, o którym wszyscy zapominają

constructEvent nie sprawdza tylko HMAC — odrzuca każde zdarzenie, którego timestamp t= jest starszy niż 300 sekund, rzucając Timestamp outside the tolerance zone. Daje to o sobie znać, gdy po kilku godzinach odtwarzasz przechwycone zdarzenie albo gdy zegar serwera się rozjechał. Podpis jest całkowicie poprawny; zawodzi wiek zdarzenia. Debugger powyżej pokazuje wiek timestampu, co pozwala odróżnić przeterminowany replay od prawdziwej niezgodności podpisu. Jeśli naprawdę potrzebujesz dłuższego okna, constructEvent przyjmuje czwarty argument tolerance w sekundach — ale najpierw napraw zegar.

Handler czy sekret? Wygeneruj zdarzenie, o którym wiesz, że jest poprawne

Gdy debugger mówi, że sekret jest dobry, a produkcja nadal zwraca 400, błąd tkwi w tym, jak Twój handler odczytuje body. Wyizoluj go: nasz Signer generuje payload podpisany jak przez Stripe sekretem, który kontrolujesz, więc możesz wysłać POST-em gwarantowanie poprawne zdarzenie prosto do lokalnego handlera. Jeśli przejdzie, Twój kod weryfikacji jest w porządku, a problemem jest sekret albo middleware. Jeśli nie, handler zmienia body — wróć do tabeli o surowym body powyżej.

Lista kontrolna diagnostyki

Wykonaj te kroki po kolei, gdy następnym razem constructEvent rzuci błąd.

1. Wklej niepasujący whsec_, surowe body i Stripe-Signature do debuggera powyżej — wskaże przyczynę, zanim zaczniesz czytać dalej.
2. Upewnij się, że body docierające do constructEvent to nietknięty surowy ciąg, a nie obiekt sparsowany i ponownie zserializowany.
3. Skopiuj sekret podpisu prosto ze strony endpointu w Dashboardzie — nie ze stripe listen, nie z innego endpointu.
4. Sprawdź, czy dla ruchu live używasz sekretu live, a dla ruchu testowego sekretu testowego.
5. Zaloguj req.headers['stripe-signature'] i sprawdź, czy nagłówek jest obecny i nie został obcięty przez proxy.
6. Sprawdź, czy timestamp t= zdarzenia nie jest starszy niż 5 minut (przeterminowany replay lub rozjechany zegar).

Przechwyć i odtwórz prawdziwe zdarzenie, które zawodzi

Nadal nic? Skieruj Stripe na Relay Webhook Toolkit albo URL do przechwytywania, złap dokładnie to żądanie, które zawodzi, i obejrzyj surowe body oraz nagłówki bajt po bajcie — a potem odtwarzaj je na swoim handlerze tyle razy, ile potrzebujesz, bez czekania na kolejne zdarzenie live.

Najczęstsze pytania