Webhooks de paiement crypto : événements, sécurité et traitement fiable des commandes

Les webhooks de paiement crypto sont des requêtes HTTP que la passerelle envoie à votre serveur à chaque changement de statut d'une facture : transfert détecté, confirmé sur la chaîne, insuffisant, excédentaire ou expiré. Votre gestionnaire vérifie la signature, met à jour la commande et déclenche la livraison. Comme les paiements crypto arrivent de façon asynchrone, plusieurs minutes après que le client a quitté votre page, la source de vérité est le webhook, pas le navigateur.

Ce guide se concentre sur la partie webhooks d'une intégration : les événements attendus, leur vérification, le traitement sûr quand un même événement arrive deux fois, puis les tests et la supervision. Pour la création de factures, consultez notre guide d'intégration de l'API de paiement crypto.

Pourquoi des webhooks plutôt que des sondages ou des redirections ?

• Une redirection n'est pas une preuve — le retour du client sur votre page « merci » ne dit rien de l'arrivée des fonds.
• Le sondage gaspille — interroger l'API toutes les quelques secondes pour chaque facture ouverte ne passe pas à l'échelle et reste en retard.
• Les webhooks sont poussés — la passerelle vous prévient dès qu'un statut change, avec une signature vérifiable.

Les événements que vous recevrez

Ce sont les noms d'événements de mistKET. D'autres passerelles utilisent des statuts similaires sous d'autres noms ; faites la correspondance avec vos états de commande en un seul endroit.

Vérifier la signature

N'importe qui peut envoyer un POST vers une URL publique : chaque webhook doit donc être authentifié. mistKET signe chaque envoi en HMAC-SHA256 et transmet ces en-têtes :

• X-Mistket-Event — nom de l'événement.
• X-Mistket-Timestamp — horodatage Unix inclus dans la signature.
• X-Mistket-Signature — sha256= suivi du HMAC de {timestamp}.{raw body} calculé avec votre secret de webhook.
• X-Mistket-Delivery — identifiant d'envoi pour les journaux.

1. Lire le corps brut — avant tout parsing JSON, car un réencodage modifie les octets.
2. Recalculer le HMAC — sur l'horodatage, un point et le corps brut, avec votre secret.
3. Comparer en temps constant — avec hash_equals, hmac.compare_digest ou crypto.timingSafeEqual.
4. Rejeter les horodatages anciens — par exemple au-delà de cinq minutes, pour bloquer les rejeux.
5. Ensuite seulement, analyser et agir — et répondre rapidement en 2xx.

La construction suit le schéma standard HMAC ; gardez le secret côté serveur et changez-le en cas de fuite.

Choisir et protéger l'URL de callback

Utilisez un chemin HTTPS dédié, par exemple /webhooks/mistket, distinct de vos pages habituelles, et transmettez-le comme callback à la création de chaque facture. Excluez-le de la protection CSRF, du cache et des redirections : une redirection 301 ou une réponse mise en cache est une cause fréquente d'échecs silencieux. N'exigez pas de cookie de session : la passerelle n'est pas un utilisateur connecté, l'authentification est la signature HMAC. Enfin, journalisez chaque envoi avec l'événement, l'identifiant de commande et le code de réponse pour répondre en quelques secondes à « avons-nous reçu le webhook ? ».

Idempotence : un même événement peut arriver deux fois

Si votre endpoint met trop de temps ou renvoie une erreur, la passerelle relance avec un délai croissant pendant des heures. Un incident réseau peut aussi livrer un événement déjà traité. Votre gestionnaire doit donc être idempotent :

• Utiliser l'identifiant de commande comme clé — retrouvez la commande référencée par la facture.
• Vérifier l'état actuel — si la commande est déjà livrée, accusez réception sans rien faire d'autre.
• Utiliser une transaction ou un verrou — pour que deux envois parallèles ne livrent pas deux fois.
• Conserver l'identifiant d'envoi — utile pour analyser les doublons.

Concevoir les états de commande autour des événements

Une machine à états simple évite la plupart des bugs : en attente → en confirmation (sur paid) → payée (sur confirmed) → livrée, avec des branches insuffisante et expirée. N'autorisez que les transitions vers l'avant : un invoice.paid reçu après un invoice.confirmed ne doit jamais faire reculer une commande. Les paiements tardifs sur des factures expirées doivent créer un enregistrement à examiner plutôt que rouvrir la commande en silence.

Gérer les cas délicats

• Paiement insuffisant — indiquez au client le montant exact manquant et qu'il peut l'envoyer sur la même page de paiement ; les paiements partiels s'additionnent.
• Paiement excédentaire — livrez, puis choisissez entre avoir et remboursement selon votre politique.
• Expiration — libérez le stock et proposez une nouvelle facture si le client veut toujours acheter.
• Mauvais réseau — cela se règle au support, pas dans le code ; affichez clairement le réseau au paiement pour l'éviter.

Tests et supervision

1. Exposer un endpoint de test — en HTTPS, avec journalisation des en-têtes et des corps bruts.
2. Déclencher chaque événement — paid, confirmed, underpaid, overpaid et expired, avec de petits paiements réels.
3. Rejouer un envoi — vérifiez que le gestionnaire ignore le doublon.
4. Casser la signature — modifiez un octet et vérifiez que la requête est rejetée.
5. Suivre les journaux d'envoi — l'espace marchand affiche chaque tentative, son code de réponse et le hash de transaction.
6. Alerter en cas d'échec — un pic de réponses non 2xx signifie des commandes non livrées.

Les bots et communautés payantes suivent le même schéma ; voyez comment il s'intègre à une conversation dans accepter les paiements crypto dans un bot Telegram.

Les webhooks avec mistKET

mistKET envoie des webhooks signés HMAC pour chaque statut de facture, relance les envois échoués avec un délai croissant et affiche dans l'espace marchand les journaux d'envoi, les montants attendus et reçus et les hashes de transaction. Les requêtes API sont signées de la même manière : une seule fonction couvre les deux sens.

Consultez les exemples de requêtes et de webhooks dans la section développeurs, les tarifs, et gérez vos clés depuis l'accès marchand. Pour obtenir un accès, postulez sur Telegram via @mistnetwork.