Guide développeurs

Comment vérifier la signature des webhooks

Chaque webhook de Capay Global est signé. Vérifier la signature tient en quelques lignes et empêche quiconque de simuler un événement de paiement réussi.

Mis à jour le 7 octobre 2026

Vérifier une livraison en Node.js

verify-capay-webhook.js
import crypto from 'node:crypto';

// rawBody: the exact bytes received, as a string. header: X-Capay-Signature.
export function verifyCapayWebhook(rawBody, header, secret) {
  const parts = header.split(',').map((p) => p.trim().split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return sigs.some(
    (s) =>
      s.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)),
  );
}

Étape par étape

  1. 1Conservez le corps brutVérifiez sur les octets exacts reçus. Analyser le JSON puis le resérialiser modifie les octets, et la vérification échoue.
  2. 2Lisez l'en-tête de signatureX-Capay-Signature a la forme t=<horodatage unix>,v1=<hex>. Pendant une rotation de secret, il porte deux valeurs v1 : acceptez la livraison si l'une d'elles correspond.
  3. 3Recalculez le HMACCalculez un HMAC-SHA256 avec le secret de signature whsec_ de votre point de terminaison sur l'horodatage, un point et le corps brut.
  4. 4Comparez de façon sûre et vérifiez l'âgeComparez à temps constant et rejetez toute livraison dont l'horodatage s'écarte de plus de 300 secondes de l'heure actuelle.
  5. 5Traitez chaque événement une seule foisLes livraisons en échec sont renvoyées : un même événement peut donc arriver plusieurs fois. Conservez les X-Capay-Event-Id déjà traités et ignorez les doublons.

Questions fréquentes

Où trouver le secret de signature ?

Dans le tableau de bord, rubrique Webhooks. Chaque point de terminaison a son propre secret whsec_, distinct de vos clés API.

Que doit répondre mon point de terminaison si la vérification échoue ?

Renvoyez un statut d'erreur et n'agissez pas sur l'événement. Seule une livraison vérifiée doit modifier une commande.

Quels en-têtes accompagnent une livraison ?

X-Capay-Signature, X-Capay-Event-Id et X-Capay-Event-Type.

Commencez dans la sandbox dès aujourd'hui

Gratuite, illimitée et ouverte dès l'inscription. Les paiements réels s'ouvrent après la vérification de votre entreprise.