Webhooks de paiement crypto : principe et mise en œuvre

Un webhook de paiement crypto est une requête HTTP qu’un service blockchain envoie à votre serveur lorsqu’un événement survient on-chain, comme l’arrivée d’un dépôt à l’adresse d’un client. Au lieu d’interroger le réseau toutes les quelques secondes pour savoir si un paiement est arrivé, vous donnez une URL au fournisseur, et c’est lui qui vous appelle.

Pour l’exploiter en production, il vous faut quatre éléments : un endpoint public, la vérification des signatures, un traitement idempotent des événements en double et une solution de repli pour les livraisons manquées. Ce guide couvre chacun d’eux.

TL;DR

• Un webhook envoie un événement à votre serveur quand un paiement ou un événement de portefeuille se produit : vous évitez l’interrogation permanente et la charge qu’elle impose à votre système.
• Vérifiez la signature de chaque requête avant de faire confiance au moindre champ. Avec Chaingateway, la signature ne couvre que l’ID de transaction : contrôlez vous-même le montant et le destinataire.
• Répondez vite avec un code 2xx, puis faites le vrai travail dans une tâche de fond.
• Considérez que chaque événement peut être répété : stockez les ID d’événement et rendez vos mises à jour de commande idempotentes.
• Gardez une tâche de réconciliation lente pour les paiements en attente. Chaingateway ne réessaie pas lui-même les notifications échouées : sans elle, une livraison manquée laisserait une commande bloquée.

Que sont les webhooks de paiement crypto ?

Un webhook est un rappel (callback). Vous enregistrez une URL et indiquez au fournisseur les événements qui vous intéressent. Quand l’un d’eux se produit, le fournisseur envoie une requête POST avec un corps JSON qui le décrit. Pour les paiements crypto, ces événements sont en général un transfert entrant vers une adresse surveillée, un transfert sortant ou un transfert de jeton sur un contrat.

L’alternative est l’interrogation périodique (polling). Votre serveur appelle une API à intervalle régulier et compare le résultat à ce qu’il avait vu la fois précédente. Le polling est simple à écrire et coûteux à exploiter. Chaque requête qui ne renvoie rien de nouveau consomme de la limite de débit, de la puissance de calcul et du temps, et le délai entre un paiement et votre réaction est aussi long que votre intervalle. Avec plusieurs chaînes et des milliers d’adresses de clients, le nombre d’appels se multiplie vite.

Les webhooks inversent le sens. Le fournisseur surveille la chaîne, compare les transactions aux adresses auxquelles vous vous êtes abonné et vous prévient une seule fois. Le délai de réaction tombe à quelques secondes, et votre propre infrastructure reste au repos tant qu’il n’y a rien à faire. Nous avons développé l’argument pour les dépôts dans comment les webhooks traitent automatiquement les dépôts.

Webhooks et polling en un coup d’œil

La dernière ligne donne la réponse pratique. Les webhooks doivent être le signal principal, et le polling un filet de sécurité lent qui ne vérifie que les paiements encore en attente. Ne lancez la vérification que pour les factures encore en attente : une livraison manquée est ainsi détectée en quelques minutes et le nombre de requêtes reste faible.

Comment un webhook détecte-t-il un paiement crypto ?

Le côté fournisseur est la partie que vous ne voyez pas, mais le comprendre explique la plupart des comportements que vous rencontrerez pendant les tests.

1. Abonnement. Vous créez un portefeuille ou enregistrez une adresse, puis vous enregistrez un webhook pour elle via l’API du fournisseur. L’abonnement contient votre URL de rappel et des filtres comme l’expéditeur, le destinataire, l’adresse du contrat et le type de transaction.
2. Surveillance. Le fournisseur exploite des nœuds pour chaque chaîne prise en charge et lit chaque nouveau bloc. Chaque transaction est comparée aux abonnements et, pour les jetons, aux journaux de transferts de contrat.
3. Décodage. Les données brutes d’une chaîne ne sont pas lisibles. Un transfert de jeton sur Ethereum est une entrée de journal encodée, et Bitcoin a des entrées et des sorties plutôt qu’un expéditeur et un destinataire. Le fournisseur en tire une charge utile lisible.
4. Livraison. Le fournisseur envoie la charge utile à votre URL. Si votre serveur ne répond pas par un code de succès, la suite dépend du fournisseur. Certains réessaient selon un calendrier. Chaingateway ne réessaie pas lui-même : il liste les notifications échouées, et vous demandez le renvoi de chacune.

Une notification Chaingateway contient les champs id, webhook_id, from, to, blocknumber, datetime, type, contractaddress, tokenid, txid et amount. Les mêmes noms de champs servent sur Ethereum, BNB Smart Chain, Polygon, Arbitrum et Tron. Les webhooks Bitcoin ne filtrent que sur l’expéditeur et le destinataire. Solana n’a pas de webhooks. Les standards de jetons comme ERC-20, BEP-20 et TRC-20 sont pris en charge, ce qui compte parce que la plupart des paiements réels sont des transferts de stablecoins plutôt que de pièces natives.

Quels événements surveiller ?

Commencez de façon restreinte. Chez Chaingateway, un webhook est défini par des filtres : chaque type d’événement correspond donc à une combinaison de filtres.

• Un transfert entrant vers une adresse de dépôt d’un client utilise to. C’est l’événement central pour créditer un compte ou marquer une facture comme payée.
• Un transfert sortant utilise from, par exemple pour voir quand un paiement sortant ou un balayage de fonds atteint la chaîne.
• Un transfert de jeton utilise type (comme ERC20 ou TRC20) avec un contractaddress.
• Un transfert de NFT utilise le champ token_id avec un type ERC721 ou TRC721.
• Le champ facultatif reference, de 255 caractères au maximum, permet de relier un webhook à une commande ou à un client de votre propre système.

Une notification annonce qu’une transaction correspondant au filtre a été vue. Vous décidez vous-même si vous la traitez comme définitive, comme l’explique la section sur la profondeur de confirmation.

Notre article sur les webhooks Polygon sans polling montre ce que cela donne sur une seule chaîne.

Comment configurer et traiter un endpoint webhook ?

L’endpoint est une route HTTPS ordinaire de votre serveur. La différence entre une démo et un gestionnaire de production tient à quelques habitudes.

Exigences de l’endpoint

L’URL doit être joignable depuis l’internet public en HTTPS. Les adresses localhost et les réseaux privés ne peuvent pas recevoir d’appels : pendant le développement, il vous faudra donc un tunnel qui expose votre port local. Réservez la route aux webhooks, n’acceptez que POST, et ne la placez pas derrière des écrans de connexion ou un middleware CSRF qui rejetterait une requête venant d’une machine.

Le gestionnaire doit répondre vite. La recommandation courante, par exemple dans la documentation des webhooks de Stripe, est de renvoyer rapidement un code de succès, avant toute logique complexe qui pourrait dépasser le délai. Succès signifie un statut 2xx tel que défini dans la RFC 9110. La même règle vaut pour les événements crypto. Si vous mettez à jour une base de données, envoyez un e-mail et appelez un système comptable avant de répondre, un service en aval lent peut amener le fournisseur à considérer la livraison comme échouée.

Un schéma fiable ressemble à ceci :

1. Lire le corps de la requête.
2. Vérifier la signature.
3. Écrire l’événement dans une file ou une table d’événements avec son ID.
4. Renvoyer 200.
5. Laisser un worker traiter l’événement en file.

Comment vérifier les signatures des webhooks ?

Quiconque trouve votre URL peut y envoyer du JSON. Si votre gestionnaire crédite un compte parce qu’une requête affirme qu’un dépôt est arrivé, une requête falsifiée équivaut à un vol. La vérification de la signature ferme cette porte.

Le schéma typique est HMAC, défini dans la RFC 2104. Le fournisseur calcule un hachage à clé avec un secret que vous seuls connaissez avec lui, et envoie le résultat dans un en-tête. Vous recalculez le hachage et vous comparez. Trois détails piègent souvent les développeurs :

• Sachez ce qui est signé. Beaucoup de fournisseurs signent tout le corps de la requête : vous devez alors vérifier sur les octets d’origine, pas sur du JSON resérialisé. Chaingateway ne signe que l’ID de transaction.
• Comparez en temps constant. Utilisez la fonction de comparaison sécurisée de votre langage plutôt qu’un simple test d’égalité.
• Vérifiez l’horodatage quand le schéma en fournit un. Rejeter les anciens horodatages limite la rediffusion d’une requête interceptée. Le schéma de Chaingateway n’a pas d’horodatage : dédupliquez donc sur l’ID de transaction.

Chaingateway envoie la signature dans un en-tête X-Signature dès que vous avez défini un secret personnel dans votre profil. La valeur est le HMAC-SHA256 du champ txid, encodé en Base64 et calculé avec ce secret. Le guide de vérification des signatures contient un gestionnaire Node.js fonctionnel, et la documentation propose des versions Python, Java et PHP. Comme seul le txid est signé, une signature valide ne prouve pas que amount ou to sont inchangés. Comparez-les à votre facture, ou à la chaîne, avant de créditer quoi que ce soit.

Stockez le secret dans une variable d’environnement ou un gestionnaire de secrets, jamais dans le dépôt, et régénérez-le s’il apparaît un jour dans un journal. Un secret régénéré prend effet immédiatement.

Comment gérer les nouvelles tentatives, les doublons et les confirmations lentes ?

Les réseaux tombent en panne et les déploiements redémarrent les serveurs. Votre gestionnaire verra tôt ou tard deux fois le même événement, par exemple après un renvoi, et parfois des événements dans le désordre. Concevez-le ainsi dès le départ.

Rendre le traitement idempotent

Chaque événement porte un élément qui l’identifie. Dans une notification Chaingateway, c’est le txid, avec le webhook_id. Enregistrez cet identifiant avec une contrainte d’unicité avant d’agir. Si l’insertion échoue parce que la clé existe, vous avez déjà vu l’événement et pouvez renvoyer 200 sans rien faire.

Rendez ensuite l’action métier elle-même répétable sans risque. « Passer la facture 1042 à payée avec la transaction X » est idempotent. « Ajouter 50 au solde » ne l’est pas. Préférez la première forme, ou liez la modification du solde à l’enregistrement d’événement unique dans une seule transaction de base de données.

Respecter la profondeur de confirmation

Une transaction qui apparaît dans un bloc n’est pas un paiement contre lequel vous pouvez expédier des marchandises. Les chaînes diffèrent par la vitesse à laquelle un bloc devient peu susceptible d’être annulé, et le bon seuil dépend du montant et de l’actif. Définissez une règle par chaîne et par taille de commande, et stockez l’état de chaque paiement : détecté, en cours de confirmation, confirmé, échoué. Le webhook qui annonce la détection doit faire passer une commande à « paiement vu », pas à « livrée ».

Paiements insuffisants, paiements excédentaires et mauvais jetons

Les clients envoient un mauvais montant plus souvent qu’on ne le croit. Votre gestionnaire doit comparer le montant et l’actif reçus à la facture, puis se brancher : montant exact, insuffisant, excédentaire ou jeton inattendu. Décidez à l’avance si vous créditez automatiquement la différence, si vous la gardez pour examen ou si vous remboursez. Une charge utile décodée, avec l’actif et le montant dans des champs séparés, réduit cette comparaison à quelques lignes de code au lieu d’un travail d’analyse.

Garder un filet de sécurité

Une livraison peut échouer, et Chaingateway ne la réessaie pas. Les notifications échouées apparaissent dans GET /api/v2/<chain>/webhooks/notifications/failed, et vous renvoyez chacune avec POST /api/v2/<chain>/webhooks/notifications/{id}/retry. Lancez une tâche planifiée, toutes les quelques minutes, qui consulte cette liste et examine les factures encore en attente au-delà d’un délai raisonnable. Quand elle trouve un paiement que votre webhook n’a jamais signalé, elle le fait passer par le même chemin de traitement. Un seul chemin de code pour les deux sources, c’est un seul ensemble de bugs.

Comment tester et surveiller un endpoint webhook ?

Construisez votre confiance par couches :

1. Test local. Écrivez un petit script qui signe un exemple de charge utile avec votre secret de test et l’envoie à votre endpoint. Vérifiez qu’une signature valide passe et qu’un txid modifié échoue.
2. Essai sur testnet. Créez un portefeuille sur un réseau de test avec l’en-tête X-Network: testnet, enregistrez un webhook et envoyez un petit transfert depuis un faucet. Vous verrez la vraie séquence d’événements, y compris le délai avant la notification, qu’aucun exemple de charge utile ne vous apprend.
3. Exercice de doublon. Envoyez cinq fois le même événement valide. Votre facture ne doit changer qu’une fois, et vos journaux doivent montrer quatre doublons ignorés.
4. Exercice d’échec. Faites renvoyer 500 à votre gestionnaire volontairement. Retrouvez ensuite la notification dans la liste des échecs, remettez le gestionnaire en état et renvoyez-la. Elle doit être traitée une seule fois.

Une fois en production, journalisez chaque ID d’événement entrant, le résultat de la vérification, le résultat du traitement et le temps écoulé. Déclenchez des alertes sur trois points : les échecs de signature (un secret mal configuré ou un attaquant), une file qui grandit (des workers qui prennent du retard) et des factures en attente bien plus longtemps que d’habitude (des problèmes de livraison silencieux).

Problèmes courants et leurs causes habituelles :

Comment commencer à recevoir des événements de paiement avec Chaingateway ?

Vous créez un webhook avec une seule requête vers POST /api/v2/<chain>/webhooks. L’exemple enregistre une surveillance de dépôt TRC20 avec une référence à votre commande :

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "TWrTTVizHkF3LxTiWE9vCnhWC7CBpNXe22",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "type": "TRC20",
    "url": "https://shop.example.com/hooks/crypto",
    "reference": "order-10442"
  }'

Les Webhooks Chaingateway fonctionnent avec l’API Blockchain : l’événement qui vous signale l’arrivée d’un dépôt et l’appel qui l’envoie plus loin relèvent ainsi du même compte.

Les forfaits sont publiés sur la page des tarifs : Plus coûte 49 € par mois, Pro 99 €, Premium 249 € et Enterprise 499 €, soit 490 €, 990 €, 2 490 € et 4 990 € par an en facturation annuelle. L’essai gratuit de 7 jours ne demande ni carte bancaire ni KYC : vous pouvez donc raccorder votre endpoint et faire d’abord les exercices ci-dessus.

Sources

• Webhooks, Stripe documentation
• HMAC: Keyed-Hashing for Message Authentication, RFC 2104
• Successful 2xx status codes, HTTP Semantics, RFC 9110

Recommandé

• The Use of Webhooks to Process Deposits Automatically
• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• Polygon Webhooks: Get Real-Time On-Chain Events Without Polling
• Real-Time Crypto Alerts: Price Apps vs. Webhook Alerts