Signature webhook Stripe invalide — trouvez pourquoi

Déboguez votre signature Stripe

Stripe est sélectionné par défaut. Le HMAC est calculé dans votre navigateur avec WebCrypto — votre whsec_ ne quitte jamais l'onglet.

Anatomie de l'en-tête Stripe-Signature

Chaque webhook Stripe arrive avec un en-tête de cette forme. Chaque champ séparé par une virgule a un rôle :

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

La chaîne signée est `${t}.${corpsBrut}` — pas le corps seul. Oubliez le préfixe t. dans un vérificateur maison et toutes les signatures échouent, même avec le bon secret.

Les 6 causes racines, dans l'ordre à vérifier

Classées par fréquence. Chacune a un symptôme qui la distingue des autres.

Le correctif du corps brut, framework par framework

La cause n°1, c'est presque toujours ça : votre framework a lu, parsé et ré-sérialisé le JSON avant que constructEvent ne le voie. Le JSON ré-sérialisé a des espaces différents, donc le HMAC ne correspond plus. Voici comment donner à chaque framework les octets intacts.

// La route webhook DOIT précéder 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()); // tout le reste

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

Collez les octets exacts dans le débogueur ci-dessus : si la signature ne correspond qu'après avoir retiré un saut de ligne final ou un champ ré-encodé, c'est que le corps a été modifié en route — pas votre secret.

Mode test vs mode live : le secret qui a l'air bon mais ne l'est pas

Stripe vous donne trois valeurs whsec_ différentes, faciles à confondre. D'abord, le secret de l'endpoint en test, affiché dans le Dashboard en mode test. Ensuite, le secret de l'endpoint en live — une valeur distincte sur le même endpoint passé en live. Enfin, le secret du CLI qu'affiche stripe listen, encore différent et valable seulement pour les événements transmis par cette session. Les trois produisent un HMAC d'apparence valide, donc l'erreur reste le générique No signatures found — rien n'indique une erreur de mode. Le symptôme : les paiements de test passent, les vrais renvoient 400. Correctif : prenez le secret de l'endpoint exact, dans le mode exact, qui reçoit le trafic.

La fenêtre de rejeu de 5 minutes que tout le monde oublie

constructEvent ne vérifie pas que le HMAC — il rejette tout événement dont l'horodatage t= dépasse 300 secondes, en levant Timestamp outside the tolerance zone. Ça mord quand vous rejouez un événement capturé des heures plus tard, ou quand l'horloge serveur a dérivé. La signature est parfaitement valide ; c'est l'âge qui échoue. Le débogueur ci-dessus affiche l'âge de l'horodatage pour distinguer un rejeu périmé d'une vraie erreur de signature. Si vous avez vraiment besoin d'une fenêtre plus large, constructEvent accepte un quatrième argument tolerance en secondes — mais réglez d'abord l'horloge.

C'est votre handler ou votre secret ? Générez un événement valide connu

Quand le débogueur dit que le secret est bon mais que la prod renvoie toujours 400, le bug est dans la façon dont votre handler lit le corps. Isolez-le : notre Signer génère un payload signé Stripe avec un secret que vous contrôlez, pour envoyer un événement garanti valide directement à votre handler local. S'il passe, votre code de vérification est bon et le problème vient du secret ou du middleware. S'il échoue, le handler modifie le corps — revenez au tableau du corps brut ci-dessus.

Checklist de diagnostic

Déroulez-les dans l'ordre la prochaine fois que constructEvent lève une erreur.

1. Collez le whsec_, le corps brut et le Stripe-Signature qui échouent dans le débogueur ci-dessus — il nomme la cause avant même que vous lisiez plus loin.
2. Vérifiez que le corps qui atteint constructEvent est la chaîne brute intacte, pas un objet parsé puis ré-sérialisé.
3. Copiez le secret de signature directement depuis la page de l'endpoint dans le Dashboard — pas depuis stripe listen, ni depuis un autre endpoint.
4. Vérifiez que vous utilisez le secret live pour le trafic live et le secret test pour le trafic test.
5. Loggez req.headers['stripe-signature'] et confirmez qu'il est présent et non tronqué par un proxy.
6. Vérifiez que l'horodatage t= de l'événement n'a pas plus de 5 minutes (rejeu périmé ou dérive d'horloge).

Capturez et rejouez le vrai événement en échec

Toujours bloqué ? Pointez Stripe vers un Relay ou une URL de capture Webhook Toolkit, attrapez la requête exacte qui échoue, et inspectez le corps brut et les en-têtes octet par octet — puis rejouez-la contre votre handler autant de fois que nécessaire, sans attendre un autre événement live.

Questions fréquentes