Qu'est-ce qu'un webhook ?

Introduction

Les webhooks permettent de recevoir des notifications en temps réel sur les événements liés aux transactions, checkouts, remboursements et autres opérations. Cette documentation détaille la configuration, les événements pris en charge et le format des payloads.

Configuration de Webhook

Dans le dashboard, accédez au menu Développeur. Vous devrez configurer les champs suivants :

• URL : L'endpoint de votre serveur qui recevra les notifications des événements.
• Token (optionnel, mais recommandé) : Un jeton de sécurité à inclure dans l'en-tête Webhook-Token pour authentifier les requêtes.

Recommandation sur le traitement

Pour éviter les timeouts, assurez-vous que le traitement de webhook dans votre endpoint est rapide. Les opérations longues (comme les calculs complexes ou les appels à des API externes) doivent être évitées ou effectuées de manière asynchrone.

Événements pris en charge

Un webhook prennent en charge les événements suivants :

[
  "checkout.create",
  "checkout.completed",
  "checkout.canceled",
  "checkout.failed",
  "transaction.create",
  "transaction.completed",
  "transaction.failed",
  "transaction.canceled",
  "transaction.pending",
  "refund.create",
  "refund.completed",
  "refund.failed",
  "refund.canceled",
  "refund-fee.create",
  "cash-out-fee.create",
  "cash-out.create"
]

Format du Payload

Chaque notification webhook est envoyée sous forme de requête HTTP POST avec un payload JSON. Voici la structure générale :

{
  "event": "string", // Nom de l'événement (par exemple, "transaction.create")
  "data": "object"
}

Exemple payload transaction

{
  "event": "string", // Nom de l'événement (par exemple, "transaction.create")
  "data": {
    "transaction": { // ou "checkout", "refund", etc., selon l'événement
      "id": "string", // Identifiant unique (UUID)
      "ref": "string", // Référence de la transaction
      "amount": "number", // Montant de la transaction
      "company": "string", // Nom de l'entreprise
      "comment": "string", // Commentaire (peut être vide)
      "wallet": "string", // Identifiant du portefeuille (UUID)
      "status": "string", // Statut (par exemple, "pending", "completed")
      "type": "string" // Type de transaction (par exemple, "money-in")
    }
  }
}

Détails des champs

• event : Une chaîne indiquant le type d'événement (voir la liste des événements ci-dessus).
• data : Contient les détails spécifiques à l'événement, généralement un objet nommé selon le type d'événement (par exemple, transaction, checkout, refund).

Sécurisation de Webhook

Si un token est configuré, chaque requête webhook inclura l'en-tête suivant :

Webhook-Token: <votre_token>

Vérifiez cet en-tête dans votre endpoint pour garantir l'authenticité des requêtes.

Meilleures pratiques

• Réponse rapide : Répondez avec un code HTTP 200 OK dès que le webhook est reçu. Traitez les données de manière asynchrone pour éviter les timeouts.
• Validation du payload : Vérifiez la structure du payload et l'authenticité via le token avant tout traitement.
• Gestion des erreurs : Implémentez une logique pour gérer les échecs de livraison (par exemple, enregistrez les événements pour un traitement ultérieur).
• Sécurité : Utilisez HTTPS pour votre endpoint et validez systématiquement le Webhook-Token.