Aller au contenu

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.

Cycle de vie d'un webhook : création avec un filtre, une transaction correspondante déclenche un POST vers votre URL, votre serveur répond 200, les livraisons échouées sont listées et renvoyées sur demande Créer un webhook POST /api/v2/{chain}/webhooks avec url et unfiltre Une transaction correspond au filtre Chaingateway envoie la notification en POST àvotre url Votre récepteur répond 200 et traite le contenu Livraison échouée ? GET .../webhooks/notifications/failed, puisPOST .../notifications/{id}/retry
Les notifications échouées ne sont pas rejouées automatiquement. Vous les listez et les renvoyez vous-même.

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
}

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 :

  1. Construire un endpoint récepteur que Chaingateway peut atteindre.
  2. Créer un webhook qui pointe vers le récepteur.
  3. Attendre un événement blockchain correspondant.
  4. 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()

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.

ChampSignification
urlObligatoire. L’URL complète de votre récepteur, chemin compris.
fromAdresse de l’expéditeur à surveiller.
toAdresse du destinataire à surveiller.
contractaddressAdresse de contrat d’un token à suivre. Non disponible sur Bitcoin.
token_idIdentifiant d’un token NFT.
typeType d’actif. Ethereum et Arbitrum : ETH, ERC20, ERC721. Polygon : MATIC, ERC20, ERC721. BNB Smart Chain : BNB, BEP20, BEP721. TRON : TRX, TRC10, TRC20, TRC721.
referenceVotre 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.

Fenêtre de terminal
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"
}'

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.

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.

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.