🔐 Sécurité des Webhooks

Pour garantir qu'une notification d'événement provient bien de ClaPay, les webhooks sont associés à un secret utilisé dans l'en-tête de chaque requête comme signature.

Secret Partagé

Cette stratégie est la méthode la plus simple pour vérifier l'origine de la requête. Le secret du webhook sera inclus dans l'en-tête, et vous devez le comparer avec celui stocké dans votre système. S'ils correspondent, vous pouvez faire confiance à la requête et procéder au traitement du paiement.

Exemple de crédentiels :

• Secret du Webhook :
  nowallet_sk_wibuTFF6v3BGCsFXK3ZbxojWhGq7htWFN8iKo+ZBsu4=

• Clé Unique du Webhook :
  nowallet_uk_w0quVMx4Vy54zk321rYyrvQeLEJA8Y5TyFxTDYJQ4VU=

Secret de Signature

La stratégie de secret de signature utilise le secret du webhook pour signer le corps haché de la requête, en l'incluant dans l'en-tête Nowallet-Signature. Cette stratégie vous permet de vérifier non seulement l'origine de la requête, mais aussi l'intégrité du corps. Nous recommandons cette stratégie si vous avez besoin d'une sécurité renforcée.

Exemple d'en-tête

Nowallet-Signature: key=6f130f57-19fa-452d-805c-1e3eec773de9,signature=9fb24256526acf253fe463ccc7fccc30ff3e43cdc10f001d6e06b24face72ff3

L'en-tête contient une signature pour chaque secret actif sur votre webhook. Habituellement, vous n'aurez qu'un seul secret actif, mais pendant une période après un changement de secret, vous pourriez en avoir plusieurs actifs. La signature est un code d'authentification de message basé sur un hachage (HMAC) généré à partir du payload en utilisant une fonction de hachage SHA256.
Pour vérifier la signature du webhook, vous devez calculer la valeur HMAC attendue basée sur le corps du message d'événement et le secret du webhook, puis vous assurer que le résultat est inclus dans les signatures de l'en-tête.

Étapes pour Vérifier l'En-tête Nowallet-Signature

1. Divisez l'en-tête par , pour obtenir les éléments key et signature.
2. Divisez chaque élément par = pour extraire les valeurs.
3. Cryptez la clé en utilisant la clé unique du webhook et HMAC-SHA256.
4. Construisez le payload :
   payload = encryptedKey + requestBody (stringifié)
5. Générez la signature attendue en utilisant HMAC-SHA256 avec le secret du webhook et le payload construit.
6. Comparez la signature générée avec celles présentes dans l'en-tête.

🧪 Exemple de Validation de Signature

Exemple de Code JavaScript

const crypto = require("crypto");

const validateSignature = (
  NowalletSignature,
  body,
  webhookSecret,
  WebhookUniqueKey
) => {
  const parts = NowalletSignature.split(",");
  const keyPart = parts.find((comp) => comp.startsWith("key="));
  const key = keyPart?.split("=")[1];
  const signatureParts = parts.filter((comp) => comp.startsWith("signature="));
  const signatures = signatureParts.map((s) => s.split("=")[1]);

  const keyEncrypted = crypto
    .createHmac("sha256", WebhookUniqueKey)
    .update(key)
    .digest("hex");
  const payload = keyEncrypted + JSON.stringify(body);
  const calculatedSignature = crypto
    .createHmac("sha256", webhookSecret)
    .update(payload)
    .digest("hex");

  return signatures.includes(calculatedSignature);
};

Testez la Signature

Vous pouvez utiliser les valeurs ci-dessous pour tester votre intégration.

Secret du Webhook

• Secret du Webhook:
  nowallet_sk_wibuTFF6v3BGCsFXK3ZbxojWhGq7htWFN8iKo+ZBsu4=

• Clé Unique du Webhook:
  nowallet_uk_w0quVMx4Vy54zk321rYyrvQeLEJA8Y5TyFxTDYJQ4VU=

Avertissement

Notez qu'il s'agit d'un texte sur une seule ligne

Corps Brut de la Requête

{
  "status": "SUCCESSFUL",
  "transaction_id": "abdoul100KWAVE",
  "additional_infos": {
    "customer_email": "[email protected]",
    "customer_lastname": "App",
    "customer_firstname": "Test"
  },
  "amount": 10000,
  "currency": "XOF",
  "fee_percent": 1,
  "fee_value": 100,
  "balance": 9900,
  "balance_before": 0,
  "balance_after": 0,
  "transaction_method": "MERCHANT",
  "transaction_phone_number": "XXXXXXXXX",
  "transaction_dialcode": "+225",
  "signature": "TEST-ba325fc6-ca09eb7b4dce-gb-7878",
  "transaction_date": "2023-11-27T03:24:31.839Z",
  "transaction_country_code": "CI",
  "transaction_service_name": "ORANGE MONEY",
  "transaction_observation": ""
}

note

Ce JSON doit être converti en chaîne (string) avant de calculer la signature. Si vous utilisez JavaScript, utilisez JSON.stringify(body)

Testez la Signature sur Jdoodle

Java sample

NodeJs sample

Cette page vous a-t-elle été utile ?