Skip to main content
Dès qu’un paiement aboutit ou échoue, Djonanko envoie une requête POST sur l’URL de webhook de votre compte. C’est le canal principal pour mettre à jour vos commandes.

Configurer l’URL

Onglet Développeur → Configuration des URLs, champ URL Webhook, puis Enregistrer.
Contraintes :
  • HTTPS avec un certificat valide.
  • Pas d’authentification (pas de Basic Auth, pas de jeton) : Djonanko n’en envoie aucune. Sécurisez la réception autrement (voir plus bas).
  • Réponse 2xx en moins de 15 secondes. Traitez en asynchrone si nécessaire.

Le payload

En-têtes envoyés : Content-Type: application/json et User-Agent: Djonanko-Webhook/1.0.
Le webhook n’est pas signé. N’accordez pas de confiance au contenu reçu : utilisez-le comme un signal, puis confirmez le statut avec GET /web-merchant/payment/status avant de livrer.

Recevoir le webhook

Sécuriser la réception

Puisque le webhook n’est ni signé ni authentifié, appliquez ces trois règles :
  1. Vérifiez le statut via l’API avant toute action irréversible (livraison, activation de service, remboursement).
  2. Soyez idempotent : un même paiement peut être notifié plusieurs fois (rejeu automatique, rejeu manuel). Utilisez reference comme clé unique.
  3. Utilisez un chemin non devinable pour votre URL, par exemple /webhooks/djonanko/8f3a…, afin de limiter les appels parasites.

Rejeu automatique

Si votre serveur ne répond pas 2xx, Djonanko réessaie automatiquement : Soit 8 tentatives sur environ 31 heures. Les réponses 400, 401, 404 et 422 sont considérées comme définitives et ne sont pas rejouées ; 403, 5xx, timeouts et erreurs réseau le sont.
Le 403 est volontairement rejouable : c’est le code renvoyé par Cloudflare lorsqu’il bloque le trafic serveur-à-serveur. Voir la section suivante.

Derrière Cloudflare ou un WAF

Cloudflare (Bot Fight Mode, challenge « Just a moment… ») peut bloquer les webhooks avec un 403. Pour les laisser passer :
  • créez une WAF Custom Rule avec l’action Skip sur le chemin de votre webhook (ex. /webhooks/djonanko*) ;
  • vérifiez que Bot Fight Mode / Super Bot Fight Mode n’est pas actif sur ce chemin ;
  • si vous filtrez par User-Agent, autorisez Djonanko-Webhook/1.0.
Une fois la règle en place, les livraisons en attente reprennent automatiquement au prochain palier, ou immédiatement via un rejeu manuel.

Surveiller et rejouer

Le dashboard et l’API exposent les livraisons en échec :
Le rejeu manuel remet le compteur à zéro : si l’envoi échoue encore, toute l’échelle de rejeu automatique redevient disponible. Rejouer une livraison déjà SUCCESS renvoie 400. Référence : GET /webhooks/failed · POST /webhooks/{id}/replay.

Tester en local

Exposez votre serveur local avec un tunnel (ngrok, Cloudflare Tunnel), enregistrez l’URL du tunnel comme webhook, puis effectuez un paiement de test de faible montant (≥ 101 FCFA). Vous pouvez aussi simuler la réception en envoyant vous-même le payload ci-dessus avec curl.