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.
Comment écrire un récepteur de webhook ?
Section intitulée « Comment écrire un récepteur de webhook ? »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}`);});from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook(): data = request.get_json() print('Received webhook:', data) return jsonify({'status': 'Webhook received'}), 200
if __name__ == '__main__': app.run(port=3000)<?phpif ($_SERVER['REQUEST_METHOD'] === 'POST') { $data = file_get_contents('php://input'); $json = json_decode($data, true); file_put_contents('php://stderr', print_r($json, TRUE)); http_response_code(200); echo json_encode(['status' => 'Webhook received']);}<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ // Register the route in routes/api.php: // Route::post('/webhook', [WebhookController::class, 'handleWebhook']); public function handleWebhook(Request $request) { $data = $request->all(); file_put_contents('php://stderr', print_r($data, TRUE)); return response()->json(['status' => 'Webhook received'], 200); }}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.frometto: l’adresse de l’émetteur et celle du destinataire, au format Tron. L’un des deux au moins est obligatoire, sauf si vous fournissezcontractaddressettoken_idà la place.contractaddress: le contrat du token à suivre.token_id: l’identifiant d’un token NFT.type: l’un deTRX,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.
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"}'import requests
url = "https://app.chaingateway.io/api/v2/tron/webhooks"payload = { "url": "https://example.com/webhook", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "type": "TRC20", "reference": "order-1042"}headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'}
response = requests.post(url, json=payload, headers=headers)print(response.json())const axios = require('axios');
const url = 'https://app.chaingateway.io/api/v2/tron/webhooks';const payload = { url: 'https://example.com/webhook', to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', type: 'TRC20', reference: 'order-1042'};const headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'};
axios.post(url, payload, { headers }) .then(response => { console.log(response.data); }) .catch(error => { console.error(error.response?.data ?? error); });<?phprequire 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();$response = $client->post('https://app.chaingateway.io/api/v2/tron/webhooks', [ 'headers' => [ 'Accept' => 'application/json', 'Authorization' => 'Bearer YOUR_API_TOKEN', ], 'json' => [ 'url' => 'https://example.com/webhook', 'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', 'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'type' => 'TRC20', 'reference' => 'order-1042' ]]);
echo $response->getBody();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.
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.
Informations importantes
Section intitulée « Informations importantes »- 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
txidpour détecter une notification déjà traitée. - Gardez votre token API dans un coffre à secrets, pas dans le code source du récepteur.
- RFC 9110, HTTP Semantics définit la méthode POST et les codes de statut utilisés par le récepteur.
- TRON TRC20 protocol interface définit les événements de token derrière les notifications TRC20.
- Ethereum token standard EIP-20 définit la même chose pour ERC-20 sur les chaînes EVM.