Webhooks

Toutes les routes nécessitent votre clé API secrète (Authorization: Bearer sk_...) ou une session dashboard. Un point de réception (webhook) appartient à votre marchand ; un abonnement (subscription) rattache ce point de réception à un type d’événement précis — un même webhook peut avoir plusieurs abonnements.

Votre marchand
│
└── Webhook (url, environment, signing_secret)
    ├── Abonnement → transaction.success
    ├── Abonnement → settlement.success
    └── Abonnement → wallet_transfer.completed

Catalogue d’events

Event	Déclenchement
`transaction.created`	Une transaction (payin ou payout) vient d’être initiée
`transaction.success`	Une transaction a été confirmée avec succès
`transaction.failed`	Une transaction a échoué
`transaction.cancelled`	Une transaction a été annulée
`settlement.requested`	Un retrait a été demandé
`settlement.approved`	Un retrait a été approuvé par un administrateur
`settlement.success`	Un retrait a été exécuté avec succès
`settlement.failed`	Un retrait a échoué
`settlement.cancelled`	Un retrait a été annulé (par vous ou refusé par un administrateur)
`wallet_transfer.requested`	Un transfert interwallet a été demandé
`wallet_transfer.completed`	Un transfert interwallet a été complété
`wallet_transfer.rejected`	Un transfert interwallet a été rejeté
`webhook.test`	Event de test, déclenché manuellement pour vérifier votre intégration

Les events settlement.* sont en cours de fiabilisation côté plateforme — le contenu de data n’est pas garanti pour ces events précis pour le moment. Le catalogue reste correct, mais évitez de dépendre de la forme exacte de leur payload tant que ce point n’est pas stabilisé.

Format de l’enveloppe

Chaque event envoyé à votre URL partage la même structure :

{
  "event": "transaction.success",
  "data": { }
}

`data` selon l’event

// transaction.success
{
  "event": "transaction.success",
  "data": {
    "id": "7c1a...",
    "reference": "TXN-2026-000456",
    "type": "PAYIN",
    "status": "SUCCESS",
    "amount": "25000.00",
    "net_amount": "24375.00",
    "currency": "XOF"
  }
}

// wallet_transfer.completed
{
  "event": "wallet_transfer.completed",
  "data": {
    "id": "1a2b...",
    "reference": "f4e5d6c7...",
    "status": "COMPLETED",
    "from_country": "BJ",
    "from_amount": "100000.00",
    "from_currency": "XOF",
    "to_country": "CM",
    "to_amount": "984.00",
    "to_currency": "XAF"
  }
}

Créer et gérer vos webhooks

Le secret de signature (signing_secret) n’est jamais renvoyé en lecture après coup, y compris par Récupérer un point de réception — c’est un champ write-only. Si vous n’en fournissez pas un à la création, SasPay en génère automatiquement un pour vous, afin de garantir qu’il ne soit jamais vide (un secret vide rendrait la signature triviale à falsifier). Notez-le précieusement au moment de la création — ou lors d’une rotation, en envoyant un nouveau signing_secret via PATCH.

Sécurité — vérifier la signature

Chaque requête envoyée à votre URL inclut deux headers, en plus du corps JSON de l’event :

POST <votre url>
Content-Type: application/json
X-Webhook-Signature: <hex sha256 HMAC, en minuscules>
X-Webhook-Event: <event_type, ex "transaction.success">

<le corps JSON exact sur lequel la signature a été calculée>

La signature est calculée côté serveur ainsi :

body = json.dumps(payload, sort_keys=True, default=str)
signature = hmac.new(signing_secret.encode(), body.encode(), hashlib.sha256).hexdigest()

Vérifiez-la côté client sur le corps brut reçu, jamais sur une re-sérialisation de payload que vous reconstruiriez vous-même — l’ordre des clés, le formatage des nombres ou des dates peuvent différer et casser la comparaison bit à bit :

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Historique de livraison

Chaque tentative de livraison (réussie, échouée, en cours de retry) est journalisée.

Pas de filtre disponible sur cette vue marchand — récupérez la liste et filtrez côté client (la vue admin, elle, dispose de filtres).

Fiabilité

5 tentatives par event : immédiat, puis +30s, +5min, +30min, +2h.
Timeout de 15s par tentative.
Après épuisement des 5 tentatives, la livraison passe en statut FAILED définitif — seul un renvoi manuel peut la relancer, elle n’est plus retentée automatiquement.

Un abonnement ne peut être créé qu’une seule fois par couple (webhook, event_type). Retenter d’abonner le même webhook au même event_type renvoie aujourd’hui une erreur serveur générique plutôt qu’un message dédié — vérifiez la liste de vos abonnements existants avant d’en créer un nouveau.

Vue d'ensemble

Paiements

Retraits

Transactions

Liens de paiement

Wallet

Marchand

KYC

Clés API

Référence

Webhooks

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

Créer et gérer vos webhooks

Sécurité — vérifier la signature

Historique de livraison

Fiabilité

​Catalogue d’events

​Format de l’enveloppe

​data selon l’event

​Créer et gérer vos webhooks

​Sécurité — vérifier la signature

​Historique de livraison

​Fiabilité

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

Créer et gérer vos webhooks

Sécurité — vérifier la signature

Historique de livraison

Fiabilité