POST sur votre URL de notification.
Configurer votre URL
À la création du compte, ou à tout moment :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_…).
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 :Superviser et rejouer
payload) est incluse : vous pouvez la traiter directement, sans attendre un rejeu.
409 WEBHOOK_ALREADY_DELIVERED).
Faire tourner le secret de signature
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.
