Walidator podpisu webhooka

Wklej niepasujący podpis

Cztery schematy podpisu

Wszystkie cztery to HMAC, ale różnią się tym, co jest hashowane i jak kodowany jest wynik. Jeden zły szczegół i każda dostawa zawodzi.

Twilio jest wyjątkiem — hashuje kanoniczny URL plus posortowane parametry, nie body. Do tego użyj walidatora podpisu Twilio.

Pięć prawdziwych przyczyn

Uszeregowane według częstości w wątkach supportu.

Pułapka surowego body

Przyczyna numer jeden: weryfikujesz wobec body sparsowanego-i-ponownie-zserializowanego zamiast dokładnych bajtów. JSON.stringify(JSON.parse(body)) zmienia odstępy i kolejność kluczy, więc HMAC już nie pasuje. Odczytaj surowe body, zanim cokolwiek je sparsuje.

// Express: keep the RAW bytes, do NOT let JSON re-serialise them
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body;                 // Buffer, exactly as received
  verify(raw, req.headers['stripe-signature'], secret);
});

# Flask: request.get_data() returns the raw body; request.json does NOT
raw = request.get_data()               # bytes, untouched
verify(raw, request.headers['X-Hub-Signature-256'], secret)

// Next.js App Router: read the text before parsing
export async function POST(req) {
  const raw = await req.text();         // sign THIS, not JSON.stringify(await req.json())
  verify(raw, req.headers.get('stripe-signature'), secret);
}

Zasada: przechwyć podpis i surowe bajty na wejściu, zweryfikuj, potem parsuj.

Timestampy i replay

Stripe i Slack wplatają timestamp w podpisywany ciąg i odrzucają wszystko starsze niż pięć minut — to ochrona przed replay, nie błąd. GitHub i Shopify nie, więc ważny podpis GitHub pozostaje ważny na zawsze. Jeśli narzędzie pokazuje ważny, ale wygasły, sekret i body są w porządku; po prostu wysyłasz ponownie stare zdarzenie. Wygeneruj świeżą dostawę zamiast wysyłać przechwyconą.

Gdy podpis się zgadza

Chcesz wysłać poprawnie podpisane zdarzenie testowe na własny endpoint? Signer webhooków tworzy je dla wszystkich sześciu dostawców. Aby przechwytywać i inspekcjonować prawdziwe dostawy, skieruj je na tunel Relay.

Najczęstsze pytania