Skip to main content
Dès qu’une opération atteint un état définitif — ou qu’un encaissement attend une action du payeur — Djonanko envoie une requête POST sur votre URL de notification.

Configurer votre URL

À la création du compte, ou à tout moment :
HTTPS obligatoire. Vous pouvez aussi surcharger l’URL par opération, via le champ callbackUrl de POST /cashin et POST /cashout — pratique pour router selon le type de flux.

Les types d’événements

Forme de la charge

data.operation a exactement la même forme que les réponses de l’API : un seul mappage à écrire de votre côté.

Vérifier la signature

Deux en-têtes accompagnent chaque notification :
v1 est un HMAC-SHA256 de la chaîne <t>.<corps brut>, calculé avec votre secret de signature (whsec_…).
Vérifiez la signature sur le corps brut, avant toute désérialisation. Si vous reparsez le JSON puis le ré-sérialisez pour calculer le HMAC, vous obtiendrez une chaîne différente (ordre des clés, espaces) et la vérification échouera systématiquement.Comparez aussi t à l’heure courante et refusez au-delà de 5 minutes : c’est ce qui rend une notification capturée inexploitable par un tiers.

Ce que votre endpoint doit faire

1

Répondre 2xx en moins de 15 secondes

Accusez réception, puis traitez en tâche de fond. Un traitement synchrone qui interroge votre base, envoie un e-mail et met à jour un ERP dépassera le délai, et la notification sera réessayée pour rien.
2

Être idempotent

La livraison est garantie « au moins une fois ». Dédupliquez sur id (l’identifiant d’événement) avant de traiter.
3

Ne rien déduire de l'ordre d'arrivée

Deux notifications d’opérations différentes peuvent arriver dans un ordre quelconque. Fiez-vous à data.operation.status, pas à la séquence de réception.
4

Être joignable en HTTPS

Et répondre sans défi anti-robot. Un pare-feu applicatif qui challenge nos appels les fait tous échouer.

Si votre endpoint est indisponible

Trois tentatives immédiates (2 s, 4 s, 8 s), puis des rejeux programmés :
Soit un rattrapage sur environ 31 heures.
Si votre endpoint renvoie 404 parce qu’il n’est pas encore déployé, la notification est abandonnée sans rejeu. Validez toujours votre URL avec POST /merchants/me/webhooks/test avant d’ouvrir le trafic.

Superviser et rejouer

La charge complète (payload) est incluse : vous pouvez la traiter directement, sans attendre un rejeu.
Le rejeu renvoie la notification à l’identique, avec une signature réhorodatée — elle passera donc votre contrôle de fenêtre temporelle. Une notification déjà livrée ne peut pas être rejouée (409 WEBHOOK_ALREADY_DELIVERED).
Surveillez cet endpoint dans votre supervision. Une accumulation de FAILED ou de ABANDONED signifie que vous perdez des confirmations d’encaissement — ce sont vos écritures comptables.

Faire tourner le secret de signature

Coupure immédiate. Les notifications sont signées avec le nouveau secret dès cet appel ; l’ancien n’est plus accepté. Déployez-le sans délai, sinon toutes vos vérifications échoueront.Si vous ne pouvez pas déployer instantanément, prévoyez une fenêtre où votre code accepte les deux secrets, et faites la rotation pendant cette fenêtre.
Le champ webhookSecretHint de GET /merchants/me donne les huit derniers caractères du secret en vigueur : utile pour vérifier que vous détenez bien la bonne version.

Les notifications ne sont pas la source de vérité

Prévoyez toujours un rattrapage par consultation. Une tâche périodique qui interroge GET /operations sur les opérations restées non définitives au-delà de leur expiresAt vous protège de toute notification perdue.