Webhooks

Découvrez comment la fonctionnalité webhook de Chaingateway peut fournir des notifications de paiement instantanées à votre serveur.

Introduction

Les webhooks de Chaingateway fournissent des notifications de paiement instantanées en temps réel à l’endpoint de vos systèmes. Pour cela, vous devez créer un webhook juste avant que le paiement soit effectué. Ce webhook dispose de plusieurs options de filtrage et vous fournit des informations de transaction dès qu’une transaction est réglée et correspond à vos critères de filtre.

Comment fonctionne un webhook

Webhooks : Les webhooks sont un moyen pour les applications d’envoyer des notifications en temps réel à d’autres applications ou services. Dans le contexte de la blockchain, les webhooks peuvent être utilisés pour recevoir des notifications sur divers événements, comme de nouveaux blocs minés, des transactions confirmées ou des événements de smart contract déclenchés.

Lorsque vous configurez un webhook, vous fournissez une URL d’endpoint dans votre application qui recevra les notifications. Chaque fois que l’événement spécifié se produit, le réseau blockchain enverra une requête HTTP POST vers votre endpoint webhook avec les données pertinentes. Votre application peut alors traiter ces données et entreprendre les actions appropriées, comme mettre à jour une base de données, envoyer des notifications ou déclencher d’autres processus.

Instant Payment Notifications (IPN) : Les IPN sont un type spécifique de webhook utilisé dans le contexte des systèmes de paiement, y compris les systèmes de paiement basés sur la blockchain. Les IPN sont généralement utilisées pour recevoir des notifications sur des événements liés aux paiements, comme des paiements réussis, échoués ou des remboursements.

Lorsqu’un paiement est effectué sur un réseau blockchain, une IPN peut être déclenchée pour notifier votre application du statut du paiement. Cela permet à votre application de mettre à jour ses enregistrements internes, de fournir un retour instantané aux utilisateurs, ou de déclencher d’autres actions en fonction du statut du paiement.

Les webhooks et les IPN sont tous deux essentiels pour créer des applications en temps réel et pilotées par les événements qui interagissent avec les réseaux blockchain. Ils permettent à votre application de rester à jour avec les derniers événements et d’entreprendre des actions immédiates en fonction de ces événements.

Exemple de message webhook

Notre système de webhook envoie des messages dans ce format

{
  "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
}

Déroulement

Pour créer un webhook, vous devez suivre les étapes suivantes :

Créer un endpoint récepteur vers lequel nous pouvons vous envoyer les webhooks
Créer un webhook sur Chaingateway en utilisant l’endpoint récepteur
Attendre les événements blockchain
Traiter la requête et renvoyer le bon code de réponse

Exemple de récepteur

Avant de créer un webhook, vous devez d’abord configurer un récepteur. Un récepteur de webhook est un composant ou un endpoint qui écoute les requêtes webhook entrantes. Il agit comme récepteur ou écouteur pour les événements déclenchés par des systèmes ou services externes. Lorsqu’un événement webhook se produit, le système émetteur effectue une requête HTTP vers l’URL du récepteur de webhook, en fournissant les données relatives à l’événement.

Le rôle du récepteur de webhook est de gérer et traiter les requêtes webhook entrantes. Il effectue généralement des actions basées sur les données reçues, comme mettre à jour une base de données, déclencher une notification, ou exécuter une logique métier spécifique.

Pour configurer un récepteur de webhook, vous devez définir un endpoint dans votre application capable de recevoir des requêtes HTTP entrantes. Cet endpoint doit être publiquement accessible afin que le système émetteur puisse lui envoyer des événements webhook. Une fois le récepteur configuré, vous pouvez configurer le système émetteur pour qu’il envoie les événements webhook vers l’URL du récepteur.

::: tip Important : Il est crucial que les récepteurs de webhook soient accessibles depuis l’extérieur. Cela signifie que les URL d’endpoint définies dans les récepteurs de webhook doivent être publiquement accessibles afin que les systèmes émetteurs puissent leur envoyer des événements webhook. Assurez-vous de configurer vos paramètres réseau, pare-feux et mesures de sécurité en conséquence pour permettre aux requêtes HTTP entrantes d’atteindre les récepteurs de webhook. :::

#!/bin/bash

# Define the endpoint URL
ENDPOINT_URL="https://example.com/webhook"

# Start a local server to receive the webhook
nc -l -p 8080 > webhook_payload.json &

# Print the server's PID
echo "Webhook receiver is running with PID: $!"

# Wait for the webhook payload to be received
sleep 5

# Read the received payload from the file
PAYLOAD=$(cat webhook_payload.json)

# Process the webhook data
# Update database, trigger notifications, execute business logic, etc.

# Send the response back to the sender
echo "Webhook received successfully" | curl -X POST -d @- $ENDPOINT_URL

# Clean up the temporary files
rm webhook_payload.json

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook_receiver():
    data = request.json()
    # Process the webhook data
    # Update database, trigger notifications, execute business logic, etc.
    return 'Webhook received successfully'

if __name__ == '__main__':
    app.run()

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
    const data = req.body;
    // Process the webhook data
    // Update database, trigger notifications, execute business logic, etc.
    res.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
{
    /*
    * you should register a route for it like
    * Route::post('/webhook', [WebhookController::class, 'handle']);
    */
    public function handle(Request $request)
    {
        // Log the webhook payload for debugging
        \Log::info('Webhook received: ', $request->all());

        // Process the webhook payload
        $eventType = $request->header('X-Event-Type');
        $payload = $request->all();

       // Do something with this webhook receiver

        // Respond to the webhook sender
        return response()->json(['status' => 'success']);
    }
}

Exemple de création

Une fois que vous avez créé votre récepteur de webhook public, nous pouvons maintenant créer le webhook.

Pour créer un webhook, vous disposez de plusieurs options pour filtrer vos événements pertinents.

from (string) : L’adresse de l’émetteur.
to (string) : L’adresse du destinataire.
contractaddress (string) : L’adresse d’un contrat que vous souhaitez suivre.
token_id (string) : Un identifiant de token NFT.
type (string enum) : Le type d’actif à suivre. Les valeurs possibles pour Ethereum sont ETH, ERC20 ou ERC721. Consultez la documentation pour les autres chaînes.

Vous devez également ajouter le paramètre url, qui doit être un nom de domaine pleinement qualifié ou une adresse IP avec la route vers l’endpoint récepteur de webhook créé précédemment.

Cela implique un ensemble requis de « url » et de l’un de « from » ou « to ». Le reste est optionnel.

Exemples :

curl --request POST \
  --url https://api.chaingateway.io/api/v2/ethereum/webhooks \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "url": "http://vonrueden.com/",
  "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "token_id": null,
  "type": "ERC20"
}'

import requests

url = "https://api.chaingateway.io/api/v2/ethereum/webhooks"

payload = {
    "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "url": "http://vonrueden.com/",
    "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
    "token_id": None,
    "type": "ERC20"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_SECRET_TOKEN"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.chaingateway.io/api/v2/ethereum/webhooks',
  headers: {'Content-Type': 'application/json', Authorization: 'YOUR_SECRET_TOKEN'},
  data: {
    from: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    to: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    url: 'http://vonrueden.com/',
    contractaddress: '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    token_id: null,
    type: 'ERC20'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.chaingateway.io/api/v2/ethereum/webhooks', [
  'body' => '{
  "from": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "url": "http://vonrueden.com/",
  "contractaddress": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
  "token_id": null,
  "type": "ERC20"
}',
  'headers' => [
    'Authorization' => 'YOUR_SECRET_TOKEN',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'YOUR_SECRET_TOKEN',
    'Content-Type' => 'application/json',
])->post('https://api.chaingateway.io/api/v2/ethereum/webhooks', [
    'from' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'to' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'url' => 'http://vonrueden.com/',
    'contractaddress' => '0x922815dFbEa128eAeaAAa185508fe078bECeFBBE',
    'token_id' => null,
    'type' => 'ERC20',
]);

echo $response->body();

La réponse ressemblera alors à ceci :

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