Webhooks de paiement blockchain expliqués
Un webhook Chaingateway est un abonnement qui fait envoyer par nos serveurs une requête HTTP POST à votre URL lorsqu’une transaction correspond au filtre défini, par exemple un transfert entrant vers l’une de vos adresses. Vous recevez ainsi des notifications de paiement instantanées sans interrogation. Les webhooks existent pour Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON et Bitcoin, mais pas pour Solana.
Comment fonctionne un webhook ?
Section intitulée « Comment fonctionne un webhook ? »Vous fournissez une URL publique et un filtre, et Chaingateway appelle l’URL une fois pour chaque transaction correspondante. L’appel est un HTTP POST avec un corps JSON. Votre application lit le corps et agit en conséquence, par exemple en marquant une commande comme payée. Ce schéma s’appelle aussi Instant Payment Notification, ou IPN, lorsqu’il sert aux paiements.
Créez le webhook peu avant le paiement attendu, avec l’adresse qui le recevra. Chaque notification contient les données ci-dessous. Le type est le type d’actif, ici un transfert de token 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}De quoi ai-je besoin avant de créer un webhook ?
Section intitulée « De quoi ai-je besoin avant de créer un webhook ? »Il vous faut un récepteur, c’est-à-dire un endpoint sur votre serveur qui accepte des requêtes POST depuis Internet. Le déroulement comporte quatre étapes :
- Construire un endpoint récepteur que Chaingateway peut atteindre.
- Créer un webhook qui pointe vers le récepteur.
- Attendre un événement blockchain correspondant.
- Lire le corps de la requête et répondre avec le statut HTTP 200.
Le récepteur doit être joignable publiquement. Vérifiez les pare-feux, les reverse proxies et les règles réseau, car une adresse privée ou un port bloqué fait échouer chaque livraison. Si vous avez défini un secret personnel, vérifiez la signature de chaque requête avant de lui faire confiance, comme décrit dans Sécurité des webhooks. Les récepteurs ci-dessous se contentent de lire le corps et de répondre.
from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook_receiver(): data = request.get_json() # Process the webhook data # Update database, trigger notifications, execute business logic, etc. return 'Webhook received successfully', 200
if __name__ == '__main__': app.run()const express = require('express');
const app = express();app.use(express.json());
app.post('/webhook', (req, res) => { const data = req.body; // Process the webhook data // Update database, trigger notifications, execute business logic, etc. res.status(200).send('Webhook received successfully');});
app.listen(3000, () => { console.log('Webhook receiver is listening on port 3000');});<?php
$data = file_get_contents('php://input');$payload = json_decode($data, true);
// Process the webhook data// Update database, trigger notifications, execute business logic, etc.
http_response_code(200);echo 'Webhook received successfully';<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ /* * Register a route for it, for example: * Route::post('/webhook', [WebhookController::class, 'handle']); */ public function handle(Request $request) { $payload = $request->all();
// Process the webhook payload \Log::info('Webhook received: ', $payload);
return response()->json(['status' => 'success']); }}Comment créer un webhook ?
Section intitulée « Comment créer un webhook ? »Envoyez une requête POST à /api/v2/{chain}/webhooks. Le corps doit contenir l’url de votre récepteur et un filtre. Les champs du filtre sont les suivants.
| Champ | Signification |
|---|---|
url | Obligatoire. L’URL complète de votre récepteur, chemin compris. |
from | Adresse de l’expéditeur à surveiller. |
to | Adresse du destinataire à surveiller. |
contractaddress | Adresse de contrat d’un token à suivre. Non disponible sur Bitcoin. |
token_id | Identifiant d’un token NFT. |
type | Type d’actif. Ethereum et Arbitrum : ETH, ERC20, ERC721. Polygon : MATIC, ERC20, ERC721. BNB Smart Chain : BNB, BEP20, BEP721. TRON : TRX, TRC10, TRC20, TRC721. |
reference | Votre propre libellé, 255 caractères au maximum. |
Fournissez from ou to. Si vous n’en fournissez aucun, l’API exige contractaddress et token_id. Les webhooks Bitcoin n’acceptent que url, from et to. Les formats d’adresse sont validés, et une adresse non conforme renvoie le statut 422 avec le nom du champ dans errors.
curl --request POST \ --url https://app.chaingateway.io/api/v2/ethereum/webhooks \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/webhook", "contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7", "type": "ERC20", "reference": "order-1042"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/webhooks"
payload = { "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE", "url": "https://example.com/webhook", "contractaddress": "0xdac17f958d2ee523a2206206994597c13d831ec7", "type": "ERC20", "reference": "order-1042"}headers = { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/webhooks', headers: {'Content-Type': 'application/json', Authorization: 'Bearer YOUR_API_TOKEN'}, data: { to: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', url: 'https://example.com/webhook', contractaddress: '0xdac17f958d2ee523a2206206994597c13d831ec7', type: 'ERC20', reference: 'order-1042' }};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/webhooks', [ 'json' => [ 'to' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE', 'url' => 'https://example.com/webhook', 'contractaddress' => '0xdac17f958d2ee523a2206206994597c13d831ec7', 'type' => 'ERC20', 'reference' => 'order-1042', ], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', ],]);
echo $response->getBody();Un appel réussi renvoie le statut 201 et l’identifiant du webhook :
{ "status": 201, "ok": true, "message": "Webhook created", "data": { "webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46" }}Vous gérez les webhooks existants avec GET /api/v2/{chain}/webhooks pour les lister, GET .../webhooks/{id} pour en lire un, PUT .../webhooks/{id} pour le modifier et DELETE .../webhooks/{id} pour le supprimer. Supprimez un webhook une fois le paiement arrivé, afin qu’il ne continue pas à correspondre à des transferts ultérieurs. PUT répond par le statut 404 et le message Webhook not found lorsque l’identifiant n’existe pas.
Que se passe-t-il quand une livraison échoue ?
Section intitulée « Que se passe-t-il quand une livraison échoue ? »Chaingateway ne rejoue pas une livraison échouée de lui-même. Les notifications échouées sont stockées, et vous les lisez et les renvoyez vous-même. Les deux endpoints sont GET /api/v2/{chain}/webhooks/notifications/failed et POST /api/v2/{chain}/webhooks/notifications/{id}/retry. La liste est paginée avec le paramètre de requête page.
Chaque entrée indique le txid, l’url cible, la response enregistrée de votre serveur et le nombre de attempts. Après le lancement d’un renvoi, la notification quitte la liste des échecs. Si le renvoi échoue aussi, elle y retourne. GET /api/v2/{chain}/webhooks/notifications liste toutes les notifications, y compris celles réussies. Exécutez une petite tâche qui consulte la liste des échecs à intervalle régulier et renvoie ce qu’elle contient, et rendez le récepteur idempotent en utilisant txid comme clé, afin qu’une notification répétée ne cause aucun dommage.
Comment détecter des dépôts sur Solana ?
Section intitulée « Comment détecter des dépôts sur Solana ? »Solana n’a aucun endpoint de webhook. Le fichier OpenAPI les définit uniquement pour Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON et Bitcoin. Pour Solana, lisez le solde de l’adresse réceptrice ou listez les transactions à intervalle fixe, puis comparez le résultat avec vos enregistrements.
- La RFC 9110, HTTP Semantics définit la méthode POST et les codes de statut 2xx avec lesquels un récepteur répond.
- Ethereum transactions décrit les champs de transaction qui apparaissent dans les notifications sur les chaînes EVM.
- La documentation des transactions TRON décrit les types de transactions derrière les valeurs
typede TRON.