Webhooks

Vérifier la signature

Chaque webhook est signé avec votre api_secret, en HMAC-SHA256 sur le corps brut de la requête (avant tout parsing JSON). Vérifiez toujours cette signature avant de traiter un webhook.

Important

Ne traitez jamais un webhook dont la signature ne correspond pas — cela signifie qu'il ne provient pas de CaurisPay.

Header reçu

X-CaurisPay-Signature: <signature hmac-sha256>

Exemple en Node.js

webhook-handler.js

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, apiSecret) {
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

app.post('/webhooks/caurispay', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-caurispay-signature'];
  const isValid = verifySignature(req.body, signature, process.env.CAURISPAY_API_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // traitez l'événement ici

  res.status(200).send('OK');
});

Bonnes pratiques

Répondez rapidement (200), traitez le lourd en asynchrone
Soyez idempotent : utilisez data.token pour éviter les doublons
N'exposez pas votre endpoint sur une route devinable