​

Webhooks

​

Signature des Livraisons et Gestion du Secret

• Création & Rotation du Secret : Lors de la création d’un endpoint webhook, un secret de signature peut être fourni ou généré automatiquement (secret: "whsec_..."). Les secrets générés par la plateforme ne sont renvoyés qu’une seule fois lors de la création. L’appel à POST /organizations/{id}/webhooks/{endpointId}/rotate-secret invalide le secret précédent immédiatement et renvoie le nouveau secret.
• Vérification de Signature : Lorsqu’un secret est actif, les livraisons sortantes incluent les en-têtes HTTP suivants :
  • X-Webhook-Signature : Format sha256=<hex_digest> (ou v1=<hex_digest>).
  • X-Webhook-Timestamp : Horodatage Unix (en secondes) de la tentative de livraison.
• Calcul HMAC : La signature est calculée par HMAC-SHA256 sur la chaîne exacte du corps brut de la requête ({timestamp}.{rawBody} ou chaîne JSON exacte). Ne parsez pas et ne ré-sérialisez pas le JSON avant vérification.

​

Exemple de Vérification de Signature en Node.js

import crypto from "node:crypto";

export function verifyWebhook({ rawBody, headers, secret }) {
  const timestamp = headers["x-webhook-timestamp"];
  const signatureHeader = headers["x-webhook-signature"];

  if (!timestamp || !signatureHeader) return false;

  // Rejeter les requêtes de plus de 5 minutes pour prévenir les attaques par rejeu
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;

  const hash = signatureHeader.replace(/^sha256=|^v1=/, "");
  const expectedHash = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expectedHash));
}

​

Enveloppe d’Événement & Schémas des Données

{
  "id": "evt_9876543210",
  "type": "payment.settled",
  "createdAt": "2026-07-25T08:30:00.000Z",
  "data": {
    "id": "c1f7b8a2-3e4d-4f1a-b2c3-5d6e7f8a9b0c",
    "reference": "ORD-2026-0042",
    "sourceAmount": 100.00,
    "sourceCurrency": "EUR",
    "targetAmount": 160000.00,
    "targetCurrency": "NGN",
    "exchangeRate": 1600.00,
    "status": "settled",
    "previousStatus": "executed"
  }
}

​

Champs des Données de Paiement

• id : Identifiant unique du paiement (uuid)
• reference : Votre référence de paiement unique
• sourceAmount : Montant dans la devise source
• sourceCurrency : Code de devise source ISO 4217
• targetAmount : Montant dans la devise cible
• targetCurrency : Code de devise cible ISO 4217
• exchangeRate : Taux de change appliqué
• status : Statut actuel (created, initiated, executed, settled, failed, cancelled)
• previousStatus (facultatif) : Statut antérieur du paiement avant la transition

​

Cycle de Vie du Paiement : payment.executed vs payment.settled

Important : payment.succeeded n’est pas un nom d’événement sortant mis en œuvre. Les événements de succès réellement émis par la plateforme sont payment.executed et payment.settled.

• payment.executed : Le prestataire a confirmé la réception des fonds. Les fonds sont crédités sur le solde en attente de votre organisation.
• payment.settled : Les fonds ont terminé leur traitement de règlement et sont disponibles sur le solde de votre portefeuille.

​

Catalogue des Événements Sortants

​

Politique de Nouvelle Tentative & Anti-Rejeu

​

Calendrier de Nouvelle Tentative avec Backoff Exponentiel

• 1 heure après le premier échec
• 2 heures après le deuxième échec
• 4 heures après le troisième échec
• 8 heures après le quatrième échec
• 16 heures après le cinquième échec
• Les tentatives s’arrêtent après 5 échecs (le délai suivant dépassant 24 heures).

​

Protection Anti-Rejeu et Déduplication

​

Tests et Renvois Manuels

• Renvoi Manuel : L’historique des livraisons est conservé. Vous pouvez réémettre manuellement un événement à l’aide de POST /organizations/{id}/webhooks/{endpointId}/deliveries/{deliveryId}/resend.
• Tests de Signature : Vous pouvez tester la vérification de signature à l’aide de vos clés de test ou dans vos suites de tests d’intégration.