🪝Webhooks

Les Webhooks sont conçus pour communiquer des mises à jour d'état en temps réel, telles que des notifications de paiement réussi. Il s'agit essentiellement d'URL que Moneroo appelle pour fournir l'ID d'un objet mis à jour. Dès réception de l'appel, vous devez récupérer le dernier statut et le traiter s'il y a eu des changements.

---

Introduction

Moneroo peut envoyer des Webhooks pour alerter votre application chaque fois qu'un événement se produit sur votre compte. Ceci est particulièrement utile pour les événements tels que les transactions échouées ou réussies. Ce mécanisme est également utile pour les services qui ne sont pas directement responsables de la création d'une requête d'API, mais qui ont besoin de la réponse à cette requête. Vous pouvez spécifier les URLs du Webhook où vous souhaitez être notifié.

Lorsqu'un événement se produit, Moneroo vous envoie un objet contenant tous les détails de l'événement via une requête HTTP POST aux URLs définies.

Moneroo.io Webhook

Types d'événements

Voici les événements que nous déclenchons actuellement.

D'autres seront ajoutés au fur et à mesure que nous étendrons nos actions à l'avenir.

Événements de paiement

Type d'événement	Description
payment.initiated	Déclenché lorsqu'un nouveau paiement est initié.
payment.success	Déclenché lorsqu'un paiement se termine avec succès.
payment.failed	Déclenché lorsqu'un paiement échoue.
payment.cancelled	Déclenché lorsqu'un paiement est annulé.

Événements de transfert

Type d'événement	Description
payout.initiated	Déclenché lorsqu'un transfert est initié.
payout.success	Déclenché lorsqu'un transfert se termine avec succès.
payout.failed	Déclenché lorsqu'un transfert échoue.

Vous pouvez utiliser ces types d'événements dans votre application pour déclencher des actions spécifiques lorsque Moneroo émet ces événements.

Structure du Webhook

Tous les contenus des Webhooks suivent une structure de base cohérente, comprenant deux éléments principaux :

• Event : Le type d'événement qui s'est produit.

• Data : Les données associées à l'événement. Le contenu de cet objet varie en fonction de l'événement, mais il contient généralement les détails de l'événement, y compris :

  • un id contenant l'ID de la transaction.

  • un status, décrivant l'état du paiement de la transaction, le paiement ou les détails du client, le cas échéant.

Exemple

Nous ne fournissons pas d'informations complètes par le biais du Webhook, vous devrez donc récupérer le dernier statut de l'objet par une requête pour retrouver un paiement/payout.

{
  "event": "payment.success",
  "data": {
    "id": "123456",
    "amount": 100,
    "currency": "USD",
    "status": "success",
    "customer": {
      "id": "123456",
      "email": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "[phone]"
    }
  }
}

Configuration

Pour configurer les Webhooks, naviguez dans le tableau de bord de votre application, accédez à la section Développeurs et cliquez sur l'onglet Webhooks.

Vous pouvez ajouter un nouveau Webhook en cliquant sur le bouton Ajouter un Webhook et en remplissant le formulaire avec les détails suivants :

• URL : L'URL du Webhook.

• Secret : La clé secrète utilisée pour signer la charge utile du Webhook.

• La clé secrète est utilisée pour signer le Webhook, ce qui vous permet de vérifier que le Webhook provient réellement de Moneroo.

• Vous pouvez ajouter un maximum de 15 Webhooks par application.

Vous pouvez également activer, désactiver ou supprimer un Webhook existant en cliquant sur les boutons correspondants.

Le Webhook est envoyé sous la forme d'une requête POST à l'URL que vous avez spécifiée. Le corps de la requête contient du JSON et des informations sur l'événement qui s'est produit. Assurez-vous que votre point d'accès peut accepter les requêtes POST et analyser les données utiles JSON.

Réception d'un Webhook

Lorsque Moneroo envoie un Webhook à votre URL, il inclut un corps en format JSON détaillant l'événement.

Par exemple, voici un corps de réponse pour l'événement payment.success⁣ :

{
  "event": "payment.success",
  "data": {
    "id": "123456",
    "amount": 100,
    "currency": "USD",
    "status": "success"
  }
}

Vous pouvez utiliser le champ event dans le contenu de la requête pour déterminer l'action que votre application doit entreprendre.

Pour accuser réception d'un Webhook, votre point d'accès doit renvoyer un code d'état HTTP 200. Tout autre code de réponse, y compris les codes 3xx, sera considéré comme un échec. Nous ne tenons pas compte du corps de la réponse ni des en-têtes.

Si votre point d'accès ne renvoie pas un code d'état HTTP 200 ou ne répond pas dans les 3 secondes, nous réessayerons le Webhook jusqu'à 3 fois avec un délai de 10 minutes entre chaque tentative.Les frameworks web tels que Rails, Laravel ou Django vérifient généralement que chaque requête POST contient un jeton CSRF.

Bien qu'il s'agisse d'une fonctionnalité de sécurité utile contre la falsification des requêtes intersites, vous devrez exempter le point de terminaison du Webhook de la protection CSRF pour garantir le fonctionnement du Webhook.

Vérification d'un Webhook

Lorsque vous recevez un Webhook, vous devez en vérifier l'origine. Chaque demande de Webhook comprend un en-tête X-Moneroo-Signature. La valeur de cet en-tête est une signature générée à l'aide du secret de signature de votre Webhook et du corps du Webhook.

Pour vérifier la signature, vous devez calculer la signature de votre côté et la comparer à la valeur de l'en-tête X-Moneroo-Signature.

La signature est calculée en utilisant HMAC-SHA256 avec le secret de signature du Webhook comme clé et le corps comme valeur.

Si la signature est valide, la réponse doit être un code d'état 200 OK. Si elle n'est pas valide, la réponse doit être 403 Forbidden.

Exemples

Veuillez remplacer 'your_webhook_signing_secret', 'your_payload' et 'header_value' par vos valeurs réelles. Pour les exemples en Node.js, Java et Go, vous devez obtenir le corps de la requête et la valeur de l'en-tête à partir de votre objet de requête HTTP.

PHP

<?php
$secret = 'your_webhook_signing_secret';
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($signature, $_SERVER['HTTP_X_MONEROO_SIGNATURE'])) {
    http_response_code(200);
} else {
    http_response_code(403);
}
?>

JavaScript (Node.js)

const crypto = require("crypto");
const secret = "your_webhook_signing_secret";
const payload = req.body;
const signature = crypto
  .createHmac("sha256", secret)
  .update(JSON.stringify(payload))
  .digest("hex");

if (signature === req.headers["x-moneroo-signature"]) {
  res.sendStatus(200);
} else {
  res.sendStatus(403);
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

// Your secret key
String secret = "your_webhook_signing_secret";
String payload = "your_payload";
String XMonerooSignature = "header_value";

Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(secret_key);

String computedSignature = new String(sha256_HMAC.doFinal(payload.getBytes(StandardCharsets.UTF_8)));
if (computedSignature.equals(XMonerooSignature)) {
    System.out.println("200 OK");
} else {
    System.out.println("403 Forbidden");
}

Python

import hashlib
import hmac

secret = 'your_webhook_signing_secret'
payload = 'your_payload'
XMonerooSignature = 'header_value'

computed_signature = hmac.new(secret.encode(), msg=payload.encode(), digestmod=hashlib.sha256).hexdigest()

if computed_signature == XMonerooSignature:
    print("200 OK")
else:
    print("403 Forbidden")

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

func main() {
    secret := "your_webhook_signing_secret"
    payload := []byte("your_payload")
    XMonerooSignature := "header_value"

    h := hmac.New(sha256.New, []byte(secret))
    h.Write(payload)
    computedSignature := hex.EncodeToString(h.Sum(nil))

    if computedSignature == XMonerooSignature {
        fmt.Println("200 OK")
    } else {
        fmt.Println("403 Forbidden")
    }
}

Bonnes Pratiques de Webhook

• Ne vous fiez pas uniquement aux Webhooks : Veillez à disposer d'une stratégie de sauvegarde, telle qu'une tâche d'arrière-plan qui vérifie à intervalles réguliers l'état des transactions en attente. Cela peut s'avérer utile en cas de défaillance de votre point d'accès au Webhook.

• Utilisez un hachage secret : L'URL de votre Webhook est publique, n'importe qui peut envoyer une fausse charge utile. Nous recommandons d'utiliser un hachage secret pour authentifier les demandes.

• Toujours réinterroger : Vérifiez les détails reçus avec notre API pour garantir l'intégrité des données. Par exemple, lors de la réception d'une notification de paiement réussie, utilisez notre point de terminaison de vérification de transaction pour vérifier le statut de la transaction.

• Répondre rapidement : Votre point d'accès au Webhook doit répondre dans un certain délai pour éviter les échecs et les nouvelles tentatives. Évitez d'exécuter des tâches de longue haleine dans votre point de terminaison du Webhook afin d'éviter les dépassements de délai. Répondez immédiatement avec un code d'état 200, puis exécutez toutes les tâches longues de manière asynchrone.

• Gérer les doublons : Dans certains cas, les Webhooks peuvent être transmis plusieurs fois. Par exemple, si nous ne recevons pas de réponse de votre point d'accès, nous relançons le Webhook. Assurez-vous que votre point d'accès peut gérer des notifications de Webhooks en double.

• Gérer les échecs : En cas d'échec de votre point de terminaison, nous réessayerons le Webhook jusqu'à trois fois, avec un délai de 10 minutes entre chaque tentative. Si toutes les tentatives échouent, nous cessons d'essayer et marquons le Webhook comme ayant échoué. Vous pouvez consulter les Webhooks qui ont échoué dans votre tableau de bord.