Qu’est-ce qu’un webhook ?
Les webhooks sont des notifications HTTP envoyées par CaurisFlux vers votre serveur lorsqu’un événement se produit (paiement réussi, échec, payout complété…).
Les webhooks sont essentiels pour une intégration fiable. Ne vous fiez pas uniquement aux redirections.
Configuration
Via le Dashboard
- Allez dans Dashboard > Paramètres > Webhooks
- Cliquez sur Ajouter un endpoint
- Entrez l’URL de votre endpoint (HTTPS requis en production)
- Sélectionnez les événements à recevoir
- Copiez le secret de signature
Événements disponibles
Événements de paiement (Collect)
| Événement | Description |
|---|
payment.completed | Paiement réussi |
payment.failed | Paiement échoué |
payment.cancelled | Paiement annulé |
payment.expired | Paiement expiré |
Événements de payout (Décaissement)
| Événement | Description |
|---|
payout.completed | Payout réussi |
payout.failed | Payout échoué |
payout.cancelled | Payout annulé |
Événements de remboursement
| Événement | Description |
|---|
refund.completed | Remboursement effectué |
Structure des webhooks
| Header | Description |
|---|
X-Cauris-Signature | Signature HMAC pour vérification (format: sha256=xxx) |
X-Cauris-Timestamp | Timestamp Unix de l’envoi |
Content-Type | application/json |
Contenu du webhook
Chaque webhook contient :
event : Type d’événement (ex: payment.completed)timestamp : Date/heure de l’événementdata : Données de la transaction
Données pour payment.completed
| Champ | Description |
|---|
transactionId | Identifiant unique de la transaction |
status | Statut (completed) |
amount | Montant |
currency | Devise |
provider | Provider utilisé |
providerReference | Référence du provider |
externalReference | Votre référence |
paidAt | Date du paiement |
metadata | Métadonnées personnalisées |
Données pour payout.completed
| Champ | Description |
|---|
payoutId | Identifiant unique du payout |
externalRef | Votre référence |
status | Statut (completed) |
amount | Montant |
currency | Devise |
method | Méthode (mobile_money, bank_transfer) |
mobileNumber / bankAccount | Coordonnées du bénéficiaire |
providerReference | Référence du provider |
completedAt | Date de complétion |
Vérification de la signature
Vérifiez toujours la signature des webhooks pour éviter les attaques.
X-Cauris-Signature au format sha256=xxx.
Processus de vérification :
- Récupérez le payload brut de la requête
- Calculez le HMAC-SHA256 avec votre secret webhook
- Comparez avec la signature reçue
- Rejetez si les signatures ne correspondent pas
Codes d’erreur (failureReason / errorCode)
Erreurs de paiement
| Code | Description |
|---|
insufficient_funds | Solde insuffisant |
user_cancelled | Annulé par l’utilisateur |
timeout | Délai expiré |
provider_error | Erreur du provider |
invalid_phone | Numéro invalide |
Erreurs de payout
| Code | Description |
|---|
invalid_recipient | Bénéficiaire invalide |
insufficient_balance | Solde insuffisant (votre compte) |
provider_error | Erreur du provider |
limit_exceeded | Limite de payout dépassée |
account_blocked | Compte bénéficiaire bloqué |
Bonnes pratiques
Répondez rapidement
Retournez un 200 OK immédiatement, puis traitez l’événement en arrière-plan.
Gérez l'idempotence
Utilisez transactionId ou payoutId pour éviter de traiter le même événement deux fois.
Logguez tout
Conservez les webhooks reçus pour debug et audit.
Gérez les retries
CaurisFlux réessaie jusqu’à 5 fois en cas d’échec (1min, 5min, 30min, 2h, 24h).
Tester vos webhooks
Depuis le Dashboard : Webhooks > Envoyer un test
Ou utilisez les numéros de test en sandbox pour déclencher des webhooks réels.
