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

// 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
2. Ajoutez votre URL
3. Sélectionnez les événements à recevoir
4. Sauvegardez

Sécuriser vos webhooks

Vérification de signature

Chaque webhook inclut une signature HMAC :

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

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

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 robuste. En les configurant correctement et en suivant les bonnes pratiques, vous garantissez une expérience de paiement fluide pour vos utilisateurs.