Webhook

Scopri come la funzionalità webhook di Chaingateway può fornire notifiche di pagamento istantanee al tuo server.

Introduzione

I webhook di Chaingateway forniscono notifiche di pagamento istantanee in tempo reale all’endpoint dei tuoi sistemi. Per farlo, dovresti creare un webhook poco prima che il pagamento venga effettuato. Questo webhook dispone di diverse opzioni di filtro e ti fornisce informazioni sulla transazione non appena una transazione viene regolata e corrisponde ai tuoi criteri di filtro.

Come funziona un webhook

Webhook: I webhook sono un modo per le applicazioni di inviare notifiche in tempo reale ad altre applicazioni o servizi. Nel contesto della blockchain, i webhook possono essere usati per ricevere notifiche su vari eventi, come nuovi blocchi minati, transazioni confermate o eventi di smart contract attivati.

Quando configuri un webhook, fornisci un endpoint URL nella tua applicazione che riceverà le notifiche. Ogni volta che si verifica l’evento specificato, la rete blockchain invierà una richiesta HTTP POST al tuo endpoint webhook con i dati rilevanti. La tua applicazione può quindi elaborare questi dati e intraprendere le azioni appropriate, come aggiornare un database, inviare notifiche o attivare altri processi.

Instant Payment Notification (IPN): Le IPN sono un tipo specifico di webhook usato nel contesto dei sistemi di pagamento, inclusi i sistemi di pagamento basati su blockchain. Le IPN vengono tipicamente usate per ricevere notifiche su eventi legati ai pagamenti, come pagamenti riusciti, pagamenti falliti o rimborsi.

Quando viene effettuato un pagamento su una rete blockchain, può essere attivata una IPN per notificare alla tua applicazione lo stato del pagamento. Questo consente alla tua applicazione di aggiornare i propri registri interni, fornire un feedback istantaneo agli utenti o attivare ulteriori azioni in base allo stato del pagamento.

Sia i webhook che le IPN sono essenziali per creare applicazioni in tempo reale e basate su eventi che interagiscono con le reti blockchain. Consentono alla tua applicazione di rimanere aggiornata sugli ultimi eventi e di intraprendere azioni immediate in base a tali eventi.

Esempio di messaggio webhook

Il nostro sistema webhook pubblica messaggi in questo formato

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

Flusso di lavoro

Per creare un webhook, devi seguire questi passaggi:

Creare un endpoint ricevente a cui possiamo inviare i webhook
Creare un webhook su Chaingateway usando l’endpoint ricevente
Attendere gli eventi blockchain
Elaborare la richiesta e restituire il codice di risposta corretto

Esempio di ricevente

Prima di creare un webhook, devi prima configurare un ricevente. Un ricevente webhook è un componente o endpoint che ascolta le richieste webhook in entrata. Agisce come ricevente o listener per gli eventi attivati da sistemi o servizi esterni. Quando si verifica un evento webhook, il sistema mittente effettua una richiesta HTTP verso l’URL del ricevente webhook, fornendo i dati relativi all’evento.

Il ruolo del ricevente webhook è gestire ed elaborare le richieste webhook in entrata. In genere esegue azioni basate sui dati ricevuti, come aggiornare un database, attivare una notifica o eseguire una logica di business specifica.

Per configurare un ricevente webhook, devi definire un endpoint nella tua applicazione in grado di ricevere richieste HTTP in entrata. Questo endpoint deve essere pubblicamente accessibile in modo che il sistema mittente possa inviargli eventi webhook. Una volta configurato il ricevente, puoi configurare il sistema mittente per inviare eventi webhook all’URL del ricevente.

::: tip Importante: È fondamentale che i riceventi webhook siano accessibili dall’esterno. Ciò significa che gli URL degli endpoint definiti nei riceventi webhook devono essere pubblicamente accessibili affinché i sistemi mittenti possano inviare loro eventi webhook. Assicurati di configurare di conseguenza le impostazioni di rete, i firewall e le misure di sicurezza per consentire alle richieste HTTP in entrata di raggiungere i riceventi 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']);
    }
}

Esempio di creazione

Una volta creato il tuo ricevente webhook pubblico, possiamo ora creare il webhook.

Per creare un webhook, hai diverse opzioni per filtrare i tuoi eventi rilevanti.

from (string): L’indirizzo del mittente.
to (string): L’indirizzo del destinatario.
contractaddress (string): L’indirizzo di un contratto che vuoi tracciare.
token_id (string): Un ID token NFT.
type (string enum): Il tipo di asset da tracciare. I valori possibili per Ethereum sono ETH, ERC20 o ERC721. Controlla la documentazione per le altre chain.

Devi anche aggiungere il parametro url, che deve essere un nome di dominio completamente qualificato o un indirizzo IP con il percorso verso l’endpoint ricevente webhook creato in precedenza.

Questo porta a un set richiesto di “url” e uno tra “from” o “to”. Il resto è opzionale.

esempi:

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 risposta sarà quindi simile a questa:

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