Webhooks

Erfahren Sie, wie die Webhook-Funktion von Chaingateway Ihrem Server Instant-Payment-Benachrichtigungen liefern kann.

Einführung

Die Webhooks von Chaingateway liefern Ihren Systemendpunkten Echtzeit-Instant-Payment-Benachrichtigungen. Dazu sollten Sie einen Webhook erstellen, kurz bevor die Zahlung erfolgt. Diese Webhooks verfügen über mehrere Filteroptionen und liefern Ihnen Transaktionsinformationen, sobald eine Transaktion abgewickelt wurde, die Ihren Filterkriterien entspricht.

Wie Webhooks funktionieren

Webhooks: Webhooks sind eine Möglichkeit für Anwendungen, Echtzeit-Benachrichtigungen an andere Anwendungen oder Dienste zu senden. Im Blockchain-Kontext können Webhooks verwendet werden, um Benachrichtigungen über verschiedene Ereignisse zu erhalten, etwa neu geminte Blöcke, bestätigte Transaktionen oder ausgelöste Smart-Contract-Ereignisse.

Wenn Sie einen Webhook einrichten, geben Sie einen URL-Endpunkt in Ihrer Anwendung an, der die Benachrichtigungen empfängt. Sobald das angegebene Ereignis eintritt, sendet das Blockchain-Netzwerk eine HTTP-POST-Anfrage an Ihren Webhook-Endpunkt mit den relevanten Daten. Ihre Anwendung kann diese Daten dann verarbeiten und entsprechende Aktionen ausführen, etwa eine Datenbank aktualisieren, Benachrichtigungen senden oder andere Prozesse auslösen.

Instant Payment Notifications (IPNs): IPNs sind eine spezielle Art von Webhook, die im Kontext von Zahlungssystemen verwendet wird, einschließlich blockchainbasierter Zahlungssysteme. IPNs werden typischerweise verwendet, um Benachrichtigungen über zahlungsbezogene Ereignisse zu erhalten, etwa erfolgreiche Zahlungen, fehlgeschlagene Zahlungen oder Rückerstattungen.

Wenn eine Zahlung auf einem Blockchain-Netzwerk erfolgt, kann eine IPN ausgelöst werden, um Ihre Anwendung über den Zahlungsstatus zu informieren. So kann Ihre Anwendung ihre internen Datensätze aktualisieren, Nutzern sofortiges Feedback geben oder weitere Aktionen basierend auf dem Zahlungsstatus auslösen.

Sowohl Webhooks als auch IPNs sind essenziell für den Aufbau echtzeitfähiger und ereignisgesteuerter Anwendungen, die mit Blockchain-Netzwerken interagieren. Sie ermöglichen es Ihrer Anwendung, stets über die neuesten Ereignisse informiert zu sein und sofortige Maßnahmen basierend auf diesen Ereignissen zu ergreifen.

Beispiel für eine Webhook-Nachricht

Unser Webhook-System sendet Nachrichten in diesem 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
}

Ablauf

Um einen Webhook zu erstellen, müssen Sie folgende Schritte durchlaufen:

Einen Empfängerendpunkt erstellen, an den wir Ihnen die Webhooks senden können
Einen Webhook auf Chaingateway mit dem Empfängerendpunkt erstellen
Auf Blockchain-Ereignisse warten
Die Anfrage verarbeiten und den korrekten Antwortcode zurücksenden

Beispielempfänger

Bevor Sie einen Webhook erstellen, müssen Sie zunächst einen Empfänger einrichten. Ein Webhook-Empfänger ist eine Komponente oder ein Endpunkt, der auf eingehende Webhook-Anfragen lauscht. Er fungiert als Empfänger oder Listener für Ereignisse, die von externen Systemen oder Diensten ausgelöst werden. Wenn ein Webhook-Ereignis eintritt, stellt das sendende System eine HTTP-Anfrage an die URL des Webhook-Empfängers und liefert Daten zu diesem Ereignis.

Die Aufgabe des Webhook-Empfängers besteht darin, die eingehenden Webhook-Anfragen zu verarbeiten. Er führt üblicherweise Aktionen basierend auf den empfangenen Daten aus, etwa eine Datenbank aktualisieren, eine Benachrichtigung auslösen oder spezifische Geschäftslogik ausführen.

Um einen Webhook-Empfänger einzurichten, müssen Sie in Ihrer Anwendung einen Endpunkt definieren, der eingehende HTTP-Anfragen empfangen kann. Dieser Endpunkt sollte öffentlich erreichbar sein, damit das sendende System Webhook-Ereignisse an ihn senden kann. Sobald der Empfänger eingerichtet ist, können Sie das sendende System so konfigurieren, dass es Webhook-Ereignisse an die URL des Empfängers sendet.

::: tip Wichtig: Es ist entscheidend, dass Webhook-Empfänger von außen erreichbar sind. Das bedeutet, dass die in den Webhook-Empfängern definierten Endpunkt-URLs öffentlich erreichbar sein sollten, damit die sendenden Systeme Webhook-Ereignisse an sie senden können. Stellen Sie sicher, dass Sie Ihre Netzwerkeinstellungen, Firewalls und Sicherheitsmaßnahmen entsprechend konfigurieren, um eingehende HTTP-Anfragen an die Webhook-Empfänger zuzulassen. :::

#!/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']);
    }
}

Beispiel-Erstellung

Sobald Sie Ihren öffentlichen Webhook-Empfänger erstellt haben, können wir jetzt den Webhook erstellen.

Beim Erstellen eines Webhooks haben Sie mehrere Optionen, um Ihre relevanten Ereignisse zu filtern.

from (string): Die Adresse des Absenders.
to (string): Die Adresse des Empfängers.
contractaddress (string): Die Adresse eines Contracts, den Sie verfolgen möchten.
token_id (string): Eine NFT-Token-ID.
type (string enum): Der zu verfolgende Asset-Typ. Mögliche Werte für Ethereum sind ETH, ERC20 oder ERC721. Prüfen Sie die Dokumentation für andere Chains.

Sie müssen außerdem den Parameter url hinzufügen, der ein vollständig qualifizierter Domainname oder eine IP-Adresse mit der Route zu dem zuvor erstellten Webhook-Empfängerendpunkt sein muss.

Daraus ergibt sich ein erforderliches Set aus „url” und entweder „from” oder „to”. Der Rest ist optional.

Beispiele:

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();

Die Antwort sieht dann etwa so aus:

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