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

Créer, modifier ou supprimer un webhook (ou un abonnement), ainsi que renvoyer manuellement une livraison, se fait exclusivement depuis le tableau de bord. Seule la consultation (points de réception, abonnements, historique de livraison) reste accessible par clé API — voir Accès dashboard vs. clé API.

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 le marchand 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": "PAIEMENT",
    "status": "SUCCESS",

    "amount": "25000.00",           // montant demandé
    "fee": "625.00",                // frais facturés au client
    "charged": "25625.00",          // ce que le payeur débourse réellement
    "net_amount": "25000.00",       // ce que vous recevez
    "fee_charge_mode": "ADD_ON",    // ADD_ON | DEDUCTED — décide qui paie les frais
    "currency": "XOF",

    "country": "BJ",                // code ISO 2 lettres
    "network": "mtn_bj",            // code réseau
    "msisdn": "22990000000"         // numéro débité (payin) ou crédité (payout)
  }
}

// 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"
  }
}

Comprendre les montants

amount n’est pas ce que le payeur débourse : cela dépend de fee_charge_mode.

Mode	Le payeur débourse	Vous recevez
`ADD_ON`	`charged` = `amount` + `fee`	`net_amount` = `amount`
`DEDUCTED`	`charged` = `amount`	`net_amount` = `amount` − `fee`

Pour rapprocher votre comptabilité, utilisez charged (ce qui a quitté le compte du client) et net_amount (ce qui vous revient) — jamais amount seul.

msisdn est vide sur les transactions antérieures au 17 août 2026 : le numéro n’était alors pas conservé. country, network et les montants sont toujours présents.

Consulter vos webhooks

Le secret de signature (signing_secret) n’est jamais renvoyé en lecture — ni par Lister, ni par Récupérer. Il n’apparaît qu’une seule fois, dans la réponse de création et dans celle d’une rotation de secret, y compris quand AlphaPay l’a généré pour vous. Copiez-le à ce moment-là : il n’est plus jamais réaffichable. Si vous l’avez perdu, définissez-en un nouveau depuis votre dashboard (Webhooks → Changer le secret) — les webhooks suivants seront signés avec celui-ci.

Sécurité — vérifier la signature

Chaque requête envoyée à votre URL inclut trois 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-Timestamp: <horodatage Unix, en secondes>
X-Webhook-Event: <event_type, ex "transaction.success">

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

La signature couvre l’horodatage et le corps, séparés par un point :

signed = f"{timestamp}.{body}"
signature = hmac.new(signing_secret.encode(), signed.encode(), hashlib.sha256).hexdigest()

L’horodatage est régénéré à chaque tentative de livraison : une nouvelle tentative 2 h plus tard porte le sien.

Deux contrôles, pas un seul

L’âge — rejetez si X-Webhook-Timestamp s’écarte de plus de 5 minutes de votre horloge. Sans ce contrôle, un webhook légitime intercepté reste rejouable indéfiniment : sa signature ne périme jamais.
La signature — recalculez-la sur le corps brut reçu, jamais sur une re-sérialisation de payload que vous reconstruiriez : l’ordre des clés ou le formatage des nombres peuvent différer et casser la comparaison bit à bit.

L’horodatage étant inclus dans la signature, un attaquant ne peut pas le rajeunir pour contourner le contrôle d’âge — la signature ne correspondrait plus.

const crypto = require("crypto");
const TOLERANCE_SECONDS = 300;

function isValid(rawBody, signatureHeader, timestampHeader, secret) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestampHeader)) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

<?php
const TOLERANCE_SECONDS = 300;

// Corps BRUT, jamais json_decode puis re-encode.
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '0';

if (abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
    http_response_code(403);
    exit('horodatage hors tolérance');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('signature invalide');
}

$payload = json_decode($body, true);
http_response_code(200);

import hashlib, hmac, time

TOLERANCE_SECONDS = 300

def is_valid(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Comparez toujours en temps constant (hash_equals, timingSafeEqual, hmac.compare_digest) et jamais avec == : une comparaison classique s’arrête au premier caractère différent, ce qui laisse fuiter la signature attendue par mesure du temps de réponse.

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. Un renvoi manuel se fait depuis le tableau de bord.

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 depuis le tableau de bord 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é.

Vue d'ensemble

Encaisser

Transactions

Liens de paiement

Décaissements

Solde & taux de change

Référentiels

Webhooks

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

Comprendre les montants

Consulter vos webhooks

Sécurité — vérifier la signature

Deux contrôles, pas un seul

Historique de livraison

Fiabilité

​Catalogue d’events

​Format de l’enveloppe

​data selon l’event

​Comprendre les montants

​Consulter vos webhooks

​Sécurité — vérifier la signature

​Deux contrôles, pas un seul

​Historique de livraison

​Fiabilité

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

Comprendre les montants

Consulter vos webhooks

Sécurité — vérifier la signature

Deux contrôles, pas un seul

Historique de livraison

Fiabilité