Stripe-webhook: handtekeningverificatie mislukt — ontdek waarom

Debug je Stripe-handtekening

Stripe is standaard geselecteerd. De HMAC wordt in je browser berekend met WebCrypto — je whsec_ verlaat het tabblad nooit.

Anatomie van de Stripe-Signature-header

Elke Stripe-webhook komt binnen met één header die er zo uitziet. Elk veld tussen de komma's heeft een taak:

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

De ondertekende string is `${t}.${rawBody}` — niet alleen de body. Vergeet je het voorvoegsel t. in een zelfgebouwde verifier, dan faalt elke handtekening, zelfs met het juiste secret.

De 6 hoofdoorzaken, in de volgorde waarin je ze checkt

Gerangschikt naar hoe vaak ze de boosdoener zijn. Elke oorzaak heeft een kenmerk dat haar van de andere onderscheidt.

De fix voor de ruwe body, per framework

Oorzaak #1 is bijna altijd deze: je webframework heeft de JSON gelezen, geparst en opnieuw geserialiseerd voordat constructEvent hem zag. Opnieuw geserialiseerde JSON heeft andere witruimte, dus de HMAC matcht niet meer. Zo geef je elk framework de onaangeroerde bytes.

// De webhookroute MOET vóór express.json() komen
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()); // al het andere

export async function POST(req: Request) {
  const body = await req.text();            // ruw, onaangeroerd
  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 });
}

Plak de exacte bytes in de debugger hierboven: als de handtekening pas matcht nadat je een afsluitend regeleinde of een opnieuw ge-encodeerd veld verwijdert, is de body onderweg gewijzigd — niet je secret.

Testmodus vs. livemodus: het secret dat goed lijkt maar het niet is

Stripe geeft je drie verschillende whsec_-waarden en die zijn makkelijk te verwarren. Ten eerste het secret van het test-endpoint, dat je in het Dashboard ziet zolang je in testmodus zit. Ten tweede het secret van het live-endpoint — een aparte waarde op hetzelfde endpoint, omgezet naar live. Ten derde het CLI-secret dat stripe listen print, weer anders en alleen geldig voor events die door die sessie worden doorgestuurd. Alle drie leveren een geldig ogende HMAC op, dus de fout is steeds dezelfde generieke No signatures found — nergens staat verkeerde modus. Het kenmerk: testbetalingen verifiëren, echte betalingen geven 400. Oplossing: lees het secret uit precies het endpoint, in precies de modus, dat het verkeer ontvangt.

Het replayvenster van 5 minuten dat iedereen vergeet

constructEvent controleert niet alleen de HMAC — het weigert elk event waarvan de t=-timestamp meer dan 300 seconden oud is, met de fout Timestamp outside the tolerance zone. Dat breekt je op wanneer je een gevangen event uren later opnieuw afspeelt, of wanneer de klok van je server is gaan afwijken. De handtekening is volkomen geldig; het is de leeftijd die faalt. De debugger hierboven toont de leeftijd van de timestamp, zodat je een verouderde replay kunt onderscheiden van een echte handtekeningmismatch. Heb je echt een langer venster nodig, dan accepteert constructEvent een vierde argument tolerance in seconden — maar fix eerst de klok.

Ligt het aan je handler of aan je secret? Genereer een event waarvan je weet dat het klopt

Als de debugger zegt dat het secret klopt maar productie nog steeds 400 geeft, zit de bug in hoe je handler de body leest. Isoleer het: onze Signer genereert een payload met een Stripe-handtekening op basis van een secret dat jij beheert, zodat je een gegarandeerd geldig event rechtstreeks naar je lokale handler kunt POSTen. Slaagt het, dan is je verificatiecode in orde en ligt het probleem bij het secret of de middleware. Faalt het, dan wijzigt de handler de body — ga terug naar de tabel over de ruwe body hierboven.

Diagnostische checklist

Loop deze in volgorde af de volgende keer dat constructEvent een fout gooit.

1. Plak het falende whsec_, de ruwe body en Stripe-Signature in de debugger hierboven — hij benoemt de oorzaak voordat je verder leest.
2. Controleer dat de body die constructEvent bereikt de onaangeroerde ruwe string is, geen geparst en opnieuw geserialiseerd object.
3. Kopieer het signing-secret rechtstreeks van de pagina van het endpoint in het Dashboard — niet uit stripe listen, niet van een ander endpoint.
4. Controleer dat je het live-secret gebruikt voor liveverkeer en het test-secret voor testverkeer.
5. Log req.headers['stripe-signature'] en controleer dat hij aanwezig is en niet door een proxy is afgekapt.
6. Controleer dat de t=-timestamp van het event niet ouder is dan 5 minuten (verouderde replay of klokafwijking).

Vang het echte falende event af en speel het opnieuw af

Kom je er nog steeds niet uit? Richt Stripe op een Webhook Toolkit-Relay of een capture-URL, vang precies de request die faalt en inspecteer de ruwe body en headers byte voor byte — speel hem daarna zo vaak als nodig opnieuw af op je handler, zonder op een volgend live-event te wachten.

Veelgestelde vragen