Obriym CRMObriym CRMCustomer flow workspace
IAFonctionnalitésBien démarrerTarifsFeuille de routeIntégrationsBlog
FR
  • ukУкраїнська
  • enEnglish
  • itItaliano
  • deDeutsch
  • frFrançais
ConnexionCommencer
IAFonctionnalitésBien démarrerTarifsFeuille de routeIntégrationsBlogConnexionCommencer
Blog

Inscriptions

Le webhook d’acquisition Monobank: vérification ECDSA et pourquoi le corps de demande brute importe

Monobank signe des sangles avec ECDSA plutôt qu’un secret partagé HMAC. Voici comment la vérification fonctionne, comment mettre en cache la clé publique, et les deux erreurs qui laissent la vérification «travailler» tout en ne protégeant rien.

16 août 2026

La plupart des passerelles de paiement ukrainiennes signent leurs callbacks avec un secret partagé : prenez votre mot de passe marchand, assemblez une chaîne par une formule documentée, hachez-la, comparez. Monobank le fait différemment, et la différence est facile à rater avec les conséquences.

Monobank signe le webhook asymétriquement: il signe avec une clé privée et vous vérifiez avec la clé PUBLIQUE, que vous allez chercher dans une demande séparée. Il n’y a pas de secret partagé du tout. C’est une sécurité strictement meilleure — même une violation complète de votre base de données n’accorde aucune possibilité de créer un événement — mais il exige deux choses un système HMAC ne : la manipulation correcte du corps de la demande brute, et la mise en cache de la clé publique.

Le contrat

Signature
L’en-tête x-sign — ECDSA au-dessus de SHA-256, encodé de base64
Clé de vérification
La clé publique marchande, GET /api/merchant/pubkey (qui requiert votre X-Token)
Ce qui est signé
Les octets exacts de l’organisme de demande — pas le résultat de l’analyse et de la ré-sérialisation
Où elle arrive
L’adresse que vous avez passée dans webHookUrl lors de la création de la facture. Le API officiel ne décrit pas de webhook marchand mondial.
Correspondance des commandes
marchandPaymInfo.reference — où votre magasin met son propre identifiant de commande
Montants
En unités mineures, pas en unités monétaires entières
Monnaie
Code numérique ISO-4217: 980 hryvnia, 840 dollars, 978 euros
Le statut expiré
NON livré par webhook — qui a créé la facture suit que

Erreur une: analyse du JSON avant vérification de la signature

La signature couvre une séquence spécifique d’octets. Si votre framework analyse automatiquement le corps dans un objet et que vous le sérialisez ensuite pour le vérifier, vous vérifiez différents octets. Ordre des clés, espace blanc, représentation des nombres, absence d’ASCII : n’importe lequel d’entre eux peut différer, et ils le font.

Le pire résultat ici n’est pas "rien ne marche" mais "travaille sur des données de test et échoue sur des données réelles" : une simple charge utile survit au voyage aller-retour, alors qu’un porteur de caractères ukrainiens au nom de l’acheteur ou un montant fractionnel ne le fait pas.

Il y a une règle : lire le corps comme un texte brut, vérifier la signature contre cela, et seulement puis parse. Dans un Next.js Route Handler qui signifie `await request.text()` avant n’importe quel `request.json()` — le deuxième appel est indisponible sur la même demande de toute façon, donc la commande ici n’est pas une question de style.

Erreur deux : récupérer la clé publique sur chaque webhook

La clé publique marchande change rarement, tout en la ramassant coûte un aller-retour à Monobank et consomme votre limite de tarif. Le faire par paiement est un moyen fiable de faire échouer sous charge exactement quand les paiements sont abondants.

Mais le mettre en cache pour toujours est faux aussi : la clé peut être rééditée, puis un cache dur signifie que vous arrêtez d’accepter les paiements jusqu’au prochain déploiement.

Le schéma de travail est cache plus rafraîchissement sur échec: prendre la clé du cache et vérifier; si la vérification échoue, relire la clé une fois et vérifier à nouveau; si elle échoue encore, rejeter. La rotation de la clé se guérit alors, tandis qu’un attaquant avec une mauvaise signature vous coûte au plus une demande supplémentaire.

Une chose évidente mérite d’être déclarée parce qu’elle est souvent mal faite : la clé publique n’est PAS un secret. Ne le chiffrez pas au repos. Il n’existe que pour vérifier les signatures, et savoir qu’il n’accorde rien. Ce qui appartient crypté est le X-Token que vous utilisez pour le récupérer.

Vérification qui protège réellement

  • La vérification a échoué — rejeter la demande. Ne pas l’enregistrer et continuer "juste au cas où": un webhook sans signature valide n’est pas un événement, c’est un étranger vous disant que vous avez été payé.
  • La clé n’a pas pu être récupérée, ou le X-Token n’a pas pu être déchiffré — rejeter aussi. Échec fermé : l’indisponibilité d’un chèque n’est pas une raison de faire confiance au non-coché.
  • Comparez aussi l’identifiant marchand avec la configuration de l’adaptateur — alors un événement sur le compte d’un autre ne peut pas atterrir dans votre espace de travail même avec une signature valide.
  • Faire le paiement écrire idempotent sur l’identifiant de facture: la banque a le droit de livrer le même événement deux fois, et c’est un comportement normal plutôt qu’un défaut.
  • Ne conservez pas le numéro de carte ou CVV. Le montant, la monnaie, le statut et l’identité de la facture sont suffisants pour se rapprocher — et ce qui n’est pas dans votre base de données ne peut pas fuir.

Où mettre un paiement qui n’a trouvé aucun ordre

La signature vérifie, le montant est là, et la référence ne correspond à rien. La réaction la plus courante est de rejeter l’événement : retourner 200, n’écrire rien. C’est le pire choix disponible, car l’argent est déjà arrivé et ne laisse aucune trace dans votre système.

La pratique qui mérite d’être construite dès le début: stocker un tel paiement comme son propre dossier sans aucune commande jointe et le montrer dans un journal de paiement marqué non lié. Un gestionnaire l’ouvre, voit le montant et l’acheteur, et l’attache à une commande existante ou en crée une nouvelle. C’est dix minutes de modélisation de données qui supprime toute une classe de billets "nous avons payé et vous ne pouvez pas le voir".

Un callback signé s’authentifie

La tentation d’exiger "passer d’abord une connexion test, puis accepter les paiements" est compréhensible mais redondante ici: une signature ECDSA correcte plus un id marchand correspondant authentifie déjà complètement l’événement. Un test de connexion est utile en tant que diagnostic — à quel compte appartient ce jeton? — mais en en faire une condition préalable aux paiements réels fait obstacle à un client et à son argent.

Foire aux questions

En quoi la signature de Monobank diffère-t-elle de LiqPay et WayForPay?

LiqPay et WayForPay utilisent un secret partagé — SHA-1 et HMAC-MD5 respectivement, sur une chaîne documentée assemblée. Monobank utilise une ECDSA asymétrique: il n’y a pas de secret partagé et vous vérifiez avec une clé publique. Ainsi, le schéma d’un fournisseur ne doit jamais être copié sur un autre; chaque contrat provient de sa propre documentation officielle.

Un webhook peut-il être configuré pour l’ensemble du compte marchand ?

Le API officiel ne décrit pas une telle chose. L’adresse est passée dans le champ webHookUrl de chaque demande de création de facture, donc c’est le travail de votre magasin de l’inclure.

Pourquoi le statut expiré n’arrive-t-il jamais?

Monobank ne le livre pas par webhook. Si vous avez besoin de connaître des factures qui n’ont jamais été payées, qui a créé ces factures doit suivre leur état.

Est-ce que les quantités arrivent en hryvnia entière?

Non, en unités mineures. 149.90 arrive à 14990. La devise est fournie sous forme de code ISO-4217 numérique, et non de la chaîne "UAH".

Le CRM peut-il émettre un remboursement grâce à cette intégration?

Dans notre mise en œuvre, non, délibérément. L’adaptateur accepte les statuts de paiement, créant et annulant les factures, les remboursements et les éventuels frais restent avec Monobank et le magasin. Une intégration qui peut déplacer l’argent nécessite un niveau de confiance différent et un audit différent.

Une intégration prête au lieu de la vôtre

Obriym CRM accepte les webhooks signés de Monobank, LiqPay, WayForPay et Hutko dans un seul journal de paiement — avec idempotency, recoupement de commande et une notification à votre équipe.

Essayez-le gratuitement.

En savoir plus

Intégrations mentionnées

  • Monobank

    Bêta

    L’acheteur paie une facture, le CRM reçoit une confirmation signée à partir de Monobank, met le paiement sur la commande et informe immédiatement votre équipe. Pas de réconciliation des déclarations à la main.

    En savoir plus
  • LiqPay

    Bêta

    Un paiement confirmé sur le côté de LiqPay soulève une alerte d’équipe et met à jour une commande correspondante dans le CRM.

    En savoir plus
  • WayForPay

    Disponible

    Le CRM vérifie chaque résultat de paiement, alerte votre équipe et lie le paiement à une commande existante. Sans match, il reste dans une file d’attente de réconciliation claire.

    En savoir plus
  • Hutko

    Disponible

    Après chaque paiement, le CRM enregistre le résultat, alerte votre équipe et fixe le paiement à une commande existante ou le maintient dans une file d’attente de rapprochement claire.

    En savoir plus

Bêta: Beta: disponible pour se connecter aujourd’hui; les capacités du canal sont encore en cours de perfectionnement.

Commencez.

Commencez par un ordre réel, pas des données de démonstration.

Inscrivez-vous et votre espace de travail est créé automatiquement. Connectez un canal de vente, ajoutez un produit et prenez votre première commande ou demande — le CRM pointe à l’étape suivante elle-même.

Démarrer gratuitementComment commencer, étape par étape
Obriym CRMObriym CRMCustomer flow workspace

Obriym CRM réunit les ventes et le commerce en ligne : prospects, opportunités, commandes et fidélisation des clients dans un seul espace.

Un produit OBRIYM

  • crm@obriym.com
  • OBRIYM
  • Serhii Oberemchuk

Individual Entrepreneur Oberemchuk Serhii Oleksandrovych · Enregistrement d’État 178752761226

Produit

  • Commerce CRM
  • IA
  • Caractéristiques
  • Commencer
  • Tarifs
  • Comparer
  • Blog
  • Feuille de route
  • Intégrations
  • Documentation API

Entreprise

  • Environ OBRIYM
  • Fondateur
  • Personne à contacter
  • Feuille de route

Développeurs

  • Pour les développeurs
  • Documentation API
  • JS Widget
  • API de collecte de prospects
  • API de commandes

©2026Obriym CRM par OBRIYM. Construit pour les ventes de production et les équipes de commerce électronique.

Conditions d’utilisationOffre publiquePaiement et remboursementsPolitique de confidentialitéSous-traitantsTraitement des donnéesMentions légalesSuppression des donnéesTarifsDocumentation API