Technique

Webhooks : Recevez les notifications de paiement en temps réel

J

Jean-Pierre Mbarga

Lead Developer

20 octobre 20265 min de lecture
W

Webhooks : Recevez les notifications de paiement en temps réel

Les webhooks sont le moyen le plus fiable de recevoir les notifications de paiement. Contrairement au polling, ils vous notifient immédiatement quand un événement se produit.

Qu'est-ce qu'un webhook ?

Un webhook est une requête HTTP POST envoyée par Simiz vers votre serveur quand un événement se produit (paiement réussi, échec, etc.).

Configuration des webhooks

Étape 1 : Créer un endpoint

javascript
// Express.js

app.post('/webhooks/simiz', express.json(), (req, res) => {

const event = req.body;

console.log('Webhook reçu:', event.type);

// Traiter l'événement

res.status(200).json({ received: true });

});

Étape 2 : Configurer dans le dashboard

  1. Allez dans Paramètres > Webhooks
  1. Ajoutez votre URL
  1. Sélectionnez les événements à recevoir
  1. Sauvegardez

Sécuriser vos webhooks

Vérification de signature

Chaque webhook inclut une signature HMAC dans le header X-Simiz-Signature avec le format :

X-Simiz-Signature: t=<timestamp>,v1=<hmac_sha256_hex>
Exemple de vérification en Node.js :
javascript
const crypto = require('crypto');

function verifySignature(payload, signatureHeader, secret) {

// Parser le header: t=<timestamp>,v1=<hash>

const parts = signatureHeader.split(',');

let timestamp, hash;

for (const part of parts) {

if (part.startsWith('t=')) timestamp = parseInt(part.slice(2));

else if (part.startsWith('v1=')) hash = part.slice(3);

}

if (!timestamp || !hash) return false;

// Vérifier que le timestamp est récent (tolérance: 5 minutes)

const now = Math.floor(Date.now() / 1000);

if (Math.abs(now - timestamp) > 300) {

return false; // Rejet pour replay attack

}

// Calculer la signature attendue

const signaturePayload = ${timestamp}.${payload};

const expectedSignature = crypto

.createHmac('sha256', secret)

.update(signaturePayload)

.digest('hex');

// Comparaison timing-safe

return crypto.timingSafeEqual(

Buffer.from(hash, 'hex'),

Buffer.from(expectedSignature, 'hex')

);

}

// Utilisation

app.post('/webhooks/simiz', express.raw({type: 'application/json'}), (req, res) => {

const signature = req.headers['x-simiz-signature'];

const payload = req.body.toString();

if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {

return res.status(401).send('Invalid signature');

}

// Traiter l'événement...

res.status(200).json({ received: true });

});

Bonnes pratiques

  • Validez toujours la signature avant de traiter
  • Répondez rapidement (< 5 secondes)
  • Utilisez une file d'attente pour le traitement asynchrone
  • Gérez l'idempotence (le même webhook peut être reçu plusieurs fois)

Types d'événements

ÉvénementDescription
payment.pendingPaiement initié, en attente de confirmation
payment.successPaiement confirmé
payment.failedPaiement échoué
payment.expiredDélai dépassé
payout.successVirement effectué
payout.failedVirement échoué

Gestion des erreurs

Retry automatique

Si votre endpoint ne répond pas (timeout, erreur 5xx), Simiz réessaie automatiquement :

  • 1ère tentative : immédiate
  • 2ème tentative : +5 minutes
  • 3ème tentative : +30 minutes
  • 4ème tentative : +2 heures
  • 5ème tentative : +24 heures

Monitoring

Surveillez vos webhooks dans le dashboard :

  • Historique des événements
  • Taux de succès/échec
  • Temps de réponse

Conclusion

Les webhooks sont essentiels pour une intégration fiable. En les configurant correctement et en suivant les bonnes pratiques, vous garantissez une expérience de paiement fluide pour vos utilisateurs.

Partager cet article
J

Jean-Pierre Mbarga

Lead Developer

Passionné par les technologies financières et l'inclusion financière en Afrique francophone. Contribue régulièrement au blog Simiz sur les sujets liés aux paiements Mobile Money.

Articles similaires