Intégration Webhook API

Cette documentation explique comment recevoir et vérifier les notifications de paiement envoyées par notre API.

Vue d’ensemble

Lorsqu’un paiement est validé, notre système envoie automatiquement une requête HTTP POST vers l’URL webhook configurée sur votre compte marchand.

Votre serveur doit :

1. Recevoir les données JSON
2. Vérifier la signature HMAC
3. Traiter les données du paiement
4. Retourner une réponse HTTP 200

Requête envoyée

Méthode HTTP

POST

Headers envoyés

Content-Type: application/json

X-Signature: votre_signature_hmac

X-Timestamp: 1715350000

X-Event: payment.success

Structure des données envoyées

{

  "event": "payment.success",

  "data": {

    "id": 15,

    "order_no": "ORD-2026-001",

    "uuid": "f8d7a2c1-xxxx-xxxx",

    "account": "0700000000",

    "subtotal": 1000,

    "charge_percentage": 5,

    "total": 1050,

    "date": "2026-05-10 12:00:00"

  }

}

Vérification de la signature

Chaque requête est signée avec votre Client Secret.

La signature est générée avec :

HMAC SHA256

Formule utilisée

hash_hmac(

    'sha256',

    $timestamp . '.' . $jsonPayload,

    $clientSecret

);

Exemple PHP simple

Fichier : webhook.php

<?php
// Votre Client Secret
$clientSecret = 'VOTRE_CLIENT_SECRET';
// Récupération du body brut
$payload = file_get_contents('php://input');
// Headers reçus
$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
// Génération de la signature locale
$computedSignature = hash_hmac(
    'sha256',
    $timestamp . '.' . $payload,
    $clientSecret
);
// Vérification sécurisée
if (!hash_equals($computedSignature, $receivedSignature)) {
    http_response_code(403);
    echo json_encode([
        'success' => false,
        'message' => 'Invalid signature'
    ]);
    exit;
}
// Conversion JSON
$data = json_decode($payload, true);
// Vérification de l'événement
if ($data['event'] === 'payment.success') {
    $payment = $data['data'];
    // Exemple :
    // Mise à jour commande
    // Validation paiement
    // Livraison produit
    // Crédit utilisateur
    file_put_contents(
        'payments.log',
        json_encode($payment) . PHP_EOL,
        FILE_APPEND
    );
}
// Réponse obligatoire
http_response_code(200);
echo json_encode([
    'success' => true
]);