Integrations
Webhook
Configurer, securiser et verifier les webhooks Novasend.
Vous pouvez gérer vos webhooks en allant dans les paramêtres et dans l’onglet Webhook. Vous pouvez créer, afficher, supprimer vos wehbook.
Sécurité et Vérification
Pour garantir que les événements de transaction reçus par votre système sont authentiques, vous devez vérifier la signature HMAC.
- À la création : Vous fournissez une Clé secrète. Cette clé est stockée de manière sécurisée et sert à signer les notifications.
- À la livraison : Pour chaque notification, Novasend génère une Signature HMAC à partir de votre clé secrète et l’inclut dans les en-têtes de la requête.
- Sur votre serveur :
- Récupérez la signature dans les en-têtes.
- Calculez votre propre signature HMAC à l’aide de la Clé secrète enregistrée lors de la création.
- Comparez votre signature générée avec celle reçue dans l’en-tête.
- Si elles correspondent, la transaction est validée.
BON À SAVOIR
Le Secret Webhook est différent de votre Clé API (Secret API). Le secret est propre à chaque webhook et se trouve dans la configuration de celui-ci dans les paramètres du portail Business.
Chaque notification est signée par l’API à l’aide du secret du webhook :
X-Signature-Value: HMAC_SHA256(body, secret)Côté marchand, vous devez recalculer cette signature pour vérifier l’intégrité du message :
const crypto = require("crypto");
const signature = crypto
.createHmac("sha256", secret)
.update(JSON.stringify(body))
.digest("hex");
if (signature !== headers["x-signature-value"]) {
throw new Error("Invalid signature");
}Réponse
{
"id": "tr_bbodj27lqhckrc7yomyjlo",
"fees": 0,
"type": "payin",
"amount": 306,
"status": "processing",
"failure": null,
"currency": "XOF",
"customer": {
"name": "Souleymane Diomande",
"phoneNumber": "+2250153013761"
},
"createdAt": "2026-02-02T09:11:14.793Z",
"reference": "TRX-69806a329d1b9",
"paymentUrl": "https://pay.wave.com/c/cos-22rs5qhyr2ej6?a=306&c=XOF&m=NOVASEND%20CI%20%2A%20Conn",
"chargedAmount": 306,
"confirmationStatus": "none",
"confirmationRequired": false
}- Description des champs de la réponse
| Champ | Description |
|---|---|
| id | Identifiant unique de la transaction. |
| fees | Frais appliqués à la transaction (en XOF). |
| type | Type de transaction — ici payin (paiement entrant). |
| amount | Montant initial demandé pour la transaction (en XOF). |
| status | Statut actuel de la transaction (processing, success, failed, etc.). |
| failure | Détails de l’erreur si la transaction a échoué, sinon null. |
| currency | Devise de la transaction (code ISO), ici XOF. |
| createdAt | Horodatage ISO indiquant la date de création de la transaction. |
| reference | Référence unique définie par le marchand pour identifier la transaction. |
| paymentUrl | Lien web ou deep link permettant au client de finaliser le paiement. Si l'opérateur est Wave, ce lien redirige vers l’interface de paiement Wave. |
| chargedAmount | Montant final effectivement débité au client (en XOF). |
| confirmationStatus | Statut de la confirmation du bénéficiaire (none, pending, accepted, declined). |
| confirmationRequired | Indique si une confirmation du bénéficiaire est requise avant le traitement de la transaction. |
- customer
| Champ | Description |
|---|---|
| customer.name | Nom complet du client effectuant le paiement. |
| customer.phoneNumber | Numéro de téléphone du client au format E.164. |
À faire absolument
- Vérifier la signature HMAC avant de traiter la donnée.
- Utiliser un endpoint dédié et sécurisé (HTTPS obligatoire).
- Gérer la rejouabilité (idempotence) de chaque webhook via le champ
eventId(optionnel). - Mettre en place une file d’attente ou un traitement asynchrone côté marchand pour éviter les blocages.