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.

Un webhook par intégration

La configuration décrite ici est celle du compte : elle reçoit les évènements de tous vos appels. Si vous exploitez plusieurs intégrations (site, application mobile, back-office…), vous pouvez donner à chacune son propre webhook en créant une application et en envoyant son identifiant dans l'en-tête X-App-Id. Le webhook du compte reste utilisé pour tout appel qui ne porte pas cet en-tête.

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

Vous choisissez, à la configuration, les événements auxquels vous souscrivez.

Domaine	Événements
Checkout	checkout.create, checkout.completed, checkout.canceled, checkout.failed
Transaction	transaction.create, transaction.completed, transaction.failed, transaction.canceled, transaction.pending
Remboursement	refund.create, refund.completed, refund.failed, refund.canceled, refund-fee.create
Retrait	cash-out.create, cash-out-fee.create
Opérations en masse	cash-out.mass.completed, cash-out.mass.failed, wallet.mass.completed, wallet.mass.failed

Événements obligatoires

transaction.completed, transaction.failed et transaction.canceled sont toujours actifs : ils sont réinjectés dans votre sélection même si vous les décochez. Ce sont eux qui vous permettent de connaître l'issue réelle d'un paiement.

La liste exacte reste consultable via l'endpoint GET /api/admin/webhook/available-events, qui renvoie aussi les événements obligatoires.

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.