← Blog
10 min de lecture
|
Publié le
|
Mis à jour le

Webhooks pour les dépôts crypto : comment ça marche

Comment un webhook détecte un dépôt crypto entrant : webhook ou polling, champs du payload, vérification de la signature HMAC et notifications manquées.

Chapitres
C
Chaingateway Team
Experts blockchain

Relu par Maurice Sobiera

Un webhook est une requête HTTP qu’un service envoie à votre serveur quand un événement se produit. Pour les dépôts crypto, l’événement est une transaction qui correspond à une adresse que vous surveillez. Chaingateway envoie les détails de la transaction à votre point d’accès, et votre code crédite le client. Cela remplace l’interrogation répétée d’une API blockchain pour trouver de nouvelles transactions.

Qu’est-ce qu’un webhook ?

Un webhook est un rappel (callback) par HTTP. Vous donnez une URL à l’expéditeur, et celui-ci envoie une requête POST à cette URL quand un événement prédéfini se produit. Le corps de la requête est le payload. Voyez l’URL comme un numéro de téléphone que l’expéditeur appelle chaque fois que quelque chose se passe.

Les webhooks et les API sont deux façons d’échanger des données. Avec une API, vous tirez : votre code demande des données selon un calendrier et vérifie si quelque chose a changé. Avec un webhook, le fournisseur pousse : il vous contacte au moment de l’événement. Pousser économise des requêtes et réduit le délai. Tirer garde pourtant un rôle, car un webhook vous dit seulement que quelque chose s’est passé. Si vous voulez l’enregistrement complet ou une vérification, vous interrogez l’API.

Webhook ou polling : lequel utiliser pour les dépôts ?

Utilisez les webhooks pour apprendre rapidement un dépôt, et l’API pour le vérifier et le rapprocher. Les deux fonctionnent bien ensemble.

ApprocheAtoutFaiblesse
Polling de l’APIVous contrôlez le moment et pouvez reprendre après une panneGaspille des requêtes, et le délai est aussi long que votre intervalle
WebhookNotification peu après que la transaction est vueUne notification peut être manquée si votre point d’accès est hors service

Chez Chaingateway, les webhooks sont disponibles pour Bitcoin, Ethereum, BNB Smart Chain, Tron, Polygon et Arbitrum. Solana n’a pas de webhooks : vous y interrogez les transactions.

Comment mettre en place un webhook de dépôt ?

Créez un point d’accès récepteur, puis enregistrez un webhook pour l’adresse que vous voulez surveiller. Le point d’accès doit être joignable depuis l’internet public. Vous n’avez pas besoin d’autoriser les adresses IP de Chaingateway, car le service appelle votre URL publique comme n’importe quel autre client.

Un webhook exige une url et au moins l’un des champs from ou to. Les filtres facultatifs sont contractaddress, token_id et type, qui vaut ETH, ERC20 ou ERC721 sur Ethereum. Vous pouvez aussi définir une reference de 255 caractères au plus, par exemple votre numéro de commande. Cette requête surveille les dépôts d’un jeton ERC-20 (ici le contrat USDT) vers une adresse.

Terminal window
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
"url": "https://example.com/hooks/deposits",
"type": "ERC20",
"contractaddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"reference": "order-1042"
}'

Un appel réussi renvoie le statut 201 et l’identifiant du webhook dans data.webhook. Créez le webhook avant que le client paie, pour que le paiement ne puisse pas avoir lieu avant que la surveillance existe.

Que contient la notification ?

Chaque POST contient les champs dont vous avez besoin pour rattacher le paiement à une commande. Cet exemple provient de la documentation Chaingateway pour un transfert TRC20.

{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}

Le txid identifie la transaction, et webhook_id indique quelle surveillance s’est déclenchée. Stockez le txid avec un index unique. Si la même notification arrive deux fois, la seconde insertion échoue et vous l’ignorez.

Comment vérifier qu’une notification est authentique ?

Contrôlez l’en-tête X-Signature avant de faire confiance au payload. Chaingateway calcule un HMAC avec SHA-256 sur le txid, en prenant votre secret personnel comme clé, et envoie le résultat encodé en Base64. HMAC est défini dans la RFC 2104. Votre serveur refait le calcul et compare les deux valeurs avec une comparaison à temps constant.

Vous définissez le secret personnel dans les paramètres de votre profil. Dès qu’un secret existe, l’en-tête est ajouté à tous les webhooks sortants. La documentation sur la signature fournit du code de vérification pour Python, Java, PHP et JavaScript.

À quoi ressemble un récepteur minimal ?

Un récepteur vérifie la signature, enregistre l’événement une seule fois et répond vite. Cet exemple Express garde les identifiants de transaction déjà vus en mémoire pour rester court. En production, utilisez une table de base de données avec un index unique sur txid.

const crypto = require('crypto');
const express = require('express');
const app = express();
const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => {
const { txid, to, amount } = req.body;
const expected = crypto
.createHmac('sha256', process.env.PERSONAL_SECRET)
.update(txid)
.digest('base64');
const received = req.get('X-Signature') || '';
const valid =
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) {
seen.add(txid);
// credit the order that belongs to the address `to` for `amount`
}
res.sendStatus(200);
});
app.listen(3000);

Testez d’abord le récepteur sur un testnet. Envoyez l’en-tête X-Network: testnet quand vous créez le webhook, puis envoyez un petit transfert de test à l’adresse surveillée. La notification doit arriver avec le txid de ce transfert. La documentation conseille de créer le webhook juste avant que le paiement soit effectué : créez-le donc au moment où vous communiquez l’adresse.

Que se passe-t-il si mon serveur est hors service ?

La notification n’est pas renvoyée automatiquement. Si votre point d’accès n’accepte pas une notification, elle apparaît dans la liste des notifications échouées à GET /api/v2/{chain}/webhooks/notifications/failed. Vous déclenchez un nouvel envoi pour chaque entrée avec POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Si la nouvelle tentative échoue, l’entrée retourne dans la liste.

Renvoyez un statut de succès dès que vous avez stocké l’événement, et faites le travail lent ensuite. La RFC 9110 définit la classe 2xx des codes de statut comme signifiant que la requête a été reçue et acceptée. Contrôlez régulièrement la liste des échecs et rapprochez vos enregistrements de l’API, pour qu’une lacune ne passe pas inaperçue. Le guide de livraison des webhooks traite plus en détail les doublons et l’ordre.

Comment nous rédigeons ces articles

Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.

C
Chaingateway Team
Experts blockchain

L'équipe Chaingateway s'attache à simplifier l'intégration blockchain pour les développeurs du monde entier.