Intégration des Webhooks

Vous intégrez avec un agent de codage ?

Le serveur MCP donne cette documentation à votre agent, et son outil validate_webhook relit votre endpoint : signature vérifiée sur le corps brut, traitement idempotent, réponse rapide.

Connecter votre agent

Configuration initiale

1. Configurer l'URL du webhook

Pour configurer votre URL de webhook :

Connectez-vous au Dashboard Business
Naviguez vers Paramètres > API & Webhooks
Entrez votre URL de webhook (doit être HTTPS)
Copiez votre secret webhook (nécessaire pour vérifier les signatures)

Important : Votre endpoint webhook doit :

Utiliser HTTPS
Être accessible publiquement
Retourner un code de statut HTTP 2xx (le délai d'attente est de 5 secondes, voir Comportement des webhooks)

Combien de webhooks par magasin

Un seul. Une URL par magasin, et une URL pour l'entreprise. Un second abonnement sur le même magasin est refusé.

Pour recevoir plusieurs types d'événements, gardez un seul abonnement et triez sur le contenu reçu. N'en créez pas un par type.

Une transaction peut quand même partir vers deux URL, car il y a deux niveaux :

Portée	Reçoit
Entreprise	les transactions de tous vos magasins
Magasin	les transactions de ce magasin

Si le magasin a son propre webhook, la transaction part vers les deux URL. Si c'est la même URL des deux côtés, elle n'est appelée qu'une fois.

Après 15 échecs consécutifs, un webhook est désactivé et ne reçoit plus rien. Le compteur repart à zéro dès qu'une livraison réussit, donc une panne courte ne le déclenche pas.

Un webhook désactivé ne se réactive pas tout seul, même une fois votre endpoint réparé. Supprimez-le et recréez-le depuis le Dashboard Business. Rien ne vous prévient : surveillez vos livraisons.

2. Créer votre endpoint webhook

Votre endpoint doit :

Accepter les requêtes POST
Vérifier la signature HMAC-SHA256
Traiter le payload JSON
Retourner un code HTTP 200 pour confirmer la réception

Structure du payload

TRANSACTION_COMPLETED est la transaction elle-même, sans enveloppe ni champ event :

{
    "id": "txn_1234567890",
    "amount": {
      "amount": 10000,
      "currency": "XOF"
    },
    "fees": {
      "amount": 100,
      "currency": "XOF"
    },
    "status": "success",
    "counterpartLabel": "John Doe",
    "counterpartIdentifier": "+2250701234567",
    "paymentMethod": "wave",
    "transactionType": "PaymentRequest",
    "businessName": "Ma Boutique",
    "storeName": "Magasin Principal",
    "description": "Payment for order #12345",
    "executedAt": "2024-01-15 14:30:25",
    "transactionDetails": {
      "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
      "reference": "PAY-2024-001",
      "paymentLinkId": "abc123def456"
    }
  }

Les Service Providers réutilisent l'URL d'entreprise () pour une demande de rattachement. Jèko POSTe une enveloppe { "event": "SERVICE_PROVIDER_LINK_REQUEST", "payload": { "id", "status", "merchantBusinessId", … } }, signée avec Jeko-Signature. Ce n'est pas le payload transaction plat ci-dessus. Un abonnement events: ["TRANSACTION_COMPLETED"] ne la reçoit pas ; events: null (défaut) la reçoit. Les webhooks magasin ne la reçoivent pas. Voir Rattacher un marchand déjà inscrit. Les abonnements créés par un Service Provider sont rattachés à son magasin dédié : la liste et la suppression ne portent que sur ses propres abonnements, pas sur ceux des autres Service Providers du marchand.

Quand le webhook est envoyé

Il n'existe qu'un seul webhook transaction. Il est envoyé lorsque :

Une transaction de paiement est complétée avec succès
Une transaction de transfert est complétée avec succès
Une transaction de transfert échoue

Champs du payload

Champ	Type	Description
`id`	string	Identifiant unique de la transaction
`amount`	MoneyModel	Montant de la transaction
`fees`	MoneyModel	Frais de la transaction
`status`	string	Statut de la transaction (`pending`, `success` ou `error`)
`counterpartLabel`	string	Nom du contrepartie (client ou bénéficiaire)
`counterpartIdentifier`	string	Identifiant du contrepartie (numéro de téléphone, etc.)
`paymentMethod`	string	Méthode de paiement utilisée (wave, orange, mtn, moov, djamo, bank)
`transactionType`	string	Type de transaction (`PaymentRequest`)
`businessName`	string	Nom de l'entreprise
`storeName`	string	Nom du magasin
`description`	string	Description de la transaction
`executedAt`	string	Date d'exécution de la transaction, au format `YYYY-MM-DD HH:mm:ss`
`transactionDetails`	object	Détails supplémentaires de la transaction
`transactionDetails.id`	string?	ID de la demande de paiement ou du transfert (optionnel)
`transactionDetails.reference`	string?	Référence de la transaction (optionnel)
`transactionDetails.paymentLinkId`	string?	ID du lien de paiement si applicable (optionnel)

Types de transactions

Le champ transactionType vaut "PaymentRequest".

Ne le confondez pas avec le champ type de l'endpoint , qui vaut payment ou transfer : ce sont deux modèles différents.

Statuts de transaction

Le champ status indique le statut :

"pending" : Transaction en cours de traitement
"success" : Transaction réussie
"error" : Transaction échouée

Vérification de la signature

Tous les webhooks sont signés avec HMAC-SHA256. Vous devez vérifier la signature pour authentifier la requête.

Algorithme de vérification

L'en-tête Jeko-Signature contient le HMAC-SHA256 du corps brut, encodé en hexadécimal minuscule, sans préfixe ni horodatage : a3f5c9…, et rien d'autre.

Récupérez l'en-tête Jeko-Signature
Calculez le HMAC-SHA256 du corps de la requête (raw body) avec votre secret webhook
Comparez la signature calculée avec celle reçue

Important : Utilisez le corps de la requête brut (raw body), pas le JSON parsé.

Exemples d'intégration

Consultez Exemples de code pour des implémentations complètes dans différents langages.

Bonnes pratiques

Vérifiez toujours la signature : Ne traitez jamais un webhook sans vérifier sa signature
Idempotence : Traitez les webhooks de manière idempotente (évitez les traitements en double)
Réponse rapide : Accusez réception sans attendre la fin de votre traitement. Le délai d'attente est de 5 secondes, au-delà le webhook est réessayé
Logging : Enregistrez tous les webhooks reçus pour le débogage
Gestion d'erreurs : Gérez les erreurs gracieusement et retournez toujours un code HTTP approprié

Consultez Bonnes pratiques pour plus de détails.

On this page