Recevoir les notifications
Les webhooks transmettent les événements de vos opérations à une URL de votre application. Configurez d’abord un point de réception HTTPS qui valide l’identité du participant et la signature des messages.
Configurer un abonnement
Créez un abonnement avec POST /webhooks et le scope webhook.write. Vous pouvez cibler les événements et les alias selon le schéma de création. Le participant génère le secret HMAC partagé : conservez-le dans votre gestionnaire de secrets.
| Action | Méthode et chemin |
|---|---|
| Lister les abonnements | GET /webhooks |
| Consulter un abonnement | GET /webhooks/{id} |
| Modifier un abonnement | PUT /webhooks/{id} |
| Supprimer un abonnement | DELETE /webhooks/{id} |
| Renouveler son secret | POST /webhooks/{id}/secrets |
Les scopes et corps exacts sont disponibles dans la référence API.
Vérifier avant de traiter
Le participant est le client mTLS lorsqu’il appelle votre serveur. Vérifiez son certificat selon la chaîne de confiance convenue. La notification porte également une signature HMAC-SHA256 dans l’en-tête X-Signature.
Recalculez la signature sur les octets du corps reçu, avec le secret partagé, puis comparez-la avant tout traitement métier. Le guide BCEAO présente l’encodage hexadécimal du résultat HMAC. Une nouvelle sérialisation du JSON peut changer les octets et invalider la comparaison.
Préparez votre traitement aux livraisons répétées et rapprochez les notifications avec les références de vos opérations. Ne journalisez ni le secret ni les accès d’authentification.
Interpréter les événements
L’énumération du contrat contient PAIEMENT_RECU, PAIEMENT_ENVOYE, PAIEMENT_REJETE, RTP_RECU, RTP_REJETE, ANNULATION_DEMANDE, ANNULATION_REJETE, RETOUR_ENVOYE, RETOUR_REJETE et RETOUR_RECU.
Un paiement envoyé est notifié lorsqu’il est irrévocable. Le retour envoyé est lui aussi notifié à son irrévocabilité. Appuyez-vous sur les descriptions du contrat pour distinguer l’envoi d’un ordre de son résultat.
Faire évoluer votre réception
Lors d’une rotation, le nouveau secret est retourné immédiatement et une date d’expiration détermine la transition. Acceptez les deux secrets pendant cette période. Lors d’un changement d’URL, maintenez l’ancienne réception jusqu’à vérification de la nouvelle.
Le guide prévoit des reprises avec temporisation exponentielle pour les erreurs serveur, et un traitement particulier du statut 429. Confirmez les paramètres de livraison de votre environnement avec votre participant.