Aller au contenu

Créer des webhooks blockchain pour les dépôts

Pour recevoir des notifications de dépôt, il faut un endpoint récepteur sur votre serveur et un webhook, créé avec POST /api/v2/{chain}/webhooks. Quand une transaction correspond au filtre, Chaingateway envoie à votre endpoint une requête HTTP POST avec ses données. Ce tutoriel construit les deux pour des dépôts TRC20 sur TRON. Les mêmes étapes valent pour Ethereum, BNB Smart Chain, Polygon, Arbitrum et Bitcoin. Solana n’a pas de webhooks.

Lisez d’abord Webhooks si vous voulez les concepts et le format de la charge utile. Il vous faut un token API issu du Démarrage rapide.

Étapes du tutoriel : écrire le récepteur, le rendre accessible depuis internet, créer le webhook, envoyer une charge de test, traiter les livraisons échouées 1. Écrire le récepteur endpoint POST qui répond 200 2. Le rendre accessible URL HTTPS publique 3. Créer le webhook POST /api/v2/tron/webhooks avec url et filtre 4. Tester avec une charge curl vers votre propre récepteur 5. Traiter les échecs lister les notifications échouées, lesrenvoyer
Les étapes 1 et 2 précèdent l'étape 3, car l'URL doit fonctionner à l'arrivée du premier événement.

Un récepteur est un endpoint serveur qui accepte des requêtes HTTP POST avec un corps JSON et répond par le statut 200. Gardez le gestionnaire court : stockez la charge utile, répondez, puis faites le travail lent ensuite dans une file ou une tâche d’arrière-plan. Les exemples ci-dessous journalisent la charge utile et l’acquittent.

const express = require('express');
const app = express();
const port = 3000;
app.use(express.json());
app.post('/webhook', (req, res) => {
console.log('Received webhook:', req.body);
res.status(200).send('Webhook received');
});
app.listen(port, () => {
console.log(`Webhook receiver listening at http://localhost:${port}`);
});

Chaingateway ne peut joindre qu’une URL publique. Pendant le développement, exposez votre port local via un tunnel et utilisez l’adresse HTTPS du tunnel comme url du webhook. Vérifiez la signature de chaque requête avant d’agir, comme le décrit Sécurité des webhooks.

Comment m’abonner à un événement blockchain ?

Section intitulée « Comment m’abonner à un événement blockchain ? »

Envoyez POST /api/v2/tron/webhooks avec l’url de votre récepteur et un filtre. Le filtre décide quelles transactions déclenchent une notification.

  • url (obligatoire) : l’adresse de votre récepteur. Ce doit être une URL valide.
  • from et to : l’adresse de l’émetteur et celle du destinataire, au format Tron. L’un des deux au moins est obligatoire, sauf si vous fournissez contractaddress et token_id à la place.
  • contractaddress : le contrat du token à suivre.
  • token_id : l’identifiant d’un token NFT.
  • type : l’un de TRX, TRC10, TRC20, TRC721.
  • reference : votre propre libellé de 255 caractères maximum, par exemple un numéro de commande.

L’exemple surveille les transferts TRC20 d’un token vers une adresse de dépôt.

Fenêtre de terminal
curl --request POST \
--url https://app.chaingateway.io/api/v2/tron/webhooks \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
"url": "https://example.com/webhook",
"to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"type": "TRC20",
"reference": "order-1042"
}'

La réponse a le statut 201 et l’identifiant du webhook dans data.webhook. Conservez l’identifiant, car il sert à modifier ou supprimer le webhook.

{
"status": 201,
"ok": true,
"message": "Webhook created",
"data": {
"webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46"
}
}

Sur les autres chaînes, le chemin et les valeurs de type changent. Ethereum et Arbitrum acceptent ETH, ERC20 et ERC721, Polygon accepte MATIC, ERC20 et ERC721, BNB Smart Chain accepte BNB, BEP20 et BEP721, et Bitcoin ne prend que url, from et to. Les adresses des chaînes EVM doivent correspondre à 0x suivi de 40 caractères hexadécimaux. Pour tester sur un réseau de test, ajoutez l’en-tête X-Network: testnet à la requête de création.

Comment tester le récepteur avant l’arrivée d’un vrai dépôt ?

Section intitulée « Comment tester le récepteur avant l’arrivée d’un vrai dépôt ? »

Envoyez une notification d’exemple à votre propre endpoint avec curl. Le corps ci-dessous a les mêmes champs qu’une vraie notification. Si votre récepteur le journalise et répond 200, l’endpoint fonctionne. Envoyez ensuite un petit transfert testnet à l’adresse surveillée pour voir l’événement réel.

Fenêtre de terminal
curl --request POST \
--url https://example.com/webhook \
--header 'Content-Type: application/json' \
--data '{
"id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed",
"webhook_id": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46",
"from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN",
"to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
"blocknumber": "65542464",
"datetime": "2024-09-25 14:48:27",
"tokenid": null,
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988",
"amount": 108935
}'

Que faire des livraisons échouées et des anciens webhooks ?

Section intitulée « Que faire des livraisons échouées et des anciens webhooks ? »

Chaingateway ne renvoie pas automatiquement les livraisons échouées. GET /api/v2/tron/webhooks/notifications/failed les liste, et POST /api/v2/tron/webhooks/notifications/{id}/retry en renvoie une. Utilisez GET /api/v2/tron/webhooks pour lister vos webhooks, PUT /api/v2/tron/webhooks/{id} pour en modifier un et DELETE /api/v2/tron/webhooks/{id} pour le supprimer. Supprimez un webhook une fois sa tâche accomplie, par exemple après l’arrivée du paiement d’une commande.

  • Le récepteur doit être joignable publiquement et accepter les requêtes HTTP POST.
  • Vérifiez l’origine et l’intégrité de chaque requête avec l’en-tête X-Signature.
  • Rendez le récepteur idempotent. Utilisez le txid pour détecter une notification déjà traitée.
  • Gardez votre token API dans un coffre à secrets, pas dans le code source du récepteur.