So funktionieren Blockchain-Zahlungs-Webhooks
Ein Webhook in Chaingateway ist ein Abonnement: Unsere Server senden eine HTTP-POST-Anfrage an Ihre URL, wenn eine Transaktion zu Ihrem Filter passt, etwa eine eingehende Überweisung an eine Ihrer Adressen. So erhalten Sie Zahlungsbenachrichtigungen ohne Polling. Webhooks gibt es für Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON und Bitcoin, nicht für Solana.
Wie funktioniert ein Webhook?
Abschnitt betitelt „Wie funktioniert ein Webhook?“Sie geben eine öffentliche URL und einen Filter an, und Chaingateway ruft die URL einmal für jede passende Transaktion auf. Der Aufruf ist ein HTTP-POST mit JSON-Body. Ihre Anwendung liest den Body und reagiert darauf, zum Beispiel indem sie eine Bestellung als bezahlt markiert. Bei Zahlungen heißt dieses Muster auch Instant Payment Notification, kurz IPN.
Erstellen Sie den Webhook kurz vor der erwarteten Zahlung, mit der Adresse, die sie erhalten wird. Jede Benachrichtigung enthält die folgenden Daten. Der type ist der Asset-Typ, hier eine TRC20-Token-Überweisung.
{ "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}Was brauche ich, bevor ich einen Webhook erstelle?
Abschnitt betitelt „Was brauche ich, bevor ich einen Webhook erstelle?“Sie brauchen einen Empfänger, also einen Endpunkt auf Ihrem Server, der POST-Anfragen aus dem Internet annimmt. Der Ablauf hat vier Schritte:
- Bauen Sie einen Empfängerendpunkt, den Chaingateway erreichen kann.
- Erstellen Sie einen Webhook, der auf den Empfänger zeigt.
- Warten Sie auf ein passendes Blockchain-Ereignis.
- Lesen Sie den Request-Body und antworten Sie mit dem HTTP-Status 200.
Der Empfänger muss öffentlich erreichbar sein. Prüfen Sie Firewalls, Reverse-Proxys und Netzwerkregeln, denn eine private Adresse oder ein blockierter Port lässt jede Zustellung scheitern. Wenn Sie ein persönliches Secret gesetzt haben, prüfen Sie die Signatur jeder Anfrage, bevor Sie ihr vertrauen, wie in Webhook-Sicherheit beschrieben. Die folgenden Empfänger lesen nur den Body und antworten.
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']); }}Wie erstelle ich einen Webhook?
Abschnitt betitelt „Wie erstelle ich einen Webhook?“Senden Sie eine POST-Anfrage an /api/v2/{chain}/webhooks. Der Body braucht die url Ihres Empfängers und einen Filter. Die Filterfelder sind die folgenden.
| Feld | Bedeutung |
|---|---|
url | Erforderlich. Die vollständige URL Ihres Empfängers, einschließlich Pfad. |
from | Absenderadresse, die beobachtet wird. |
to | Empfängeradresse, die beobachtet wird. |
contractaddress | Contract-Adresse eines Tokens, den Sie verfolgen möchten. Auf Bitcoin nicht verfügbar. |
token_id | NFT-Token-ID. |
type | Asset-Typ. Ethereum und Arbitrum: ETH, ERC20, ERC721. Polygon: MATIC, ERC20, ERC721. BNB Smart Chain: BNB, BEP20, BEP721. TRON: TRX, TRC10, TRC20, TRC721. |
reference | Ihre eigene Bezeichnung, bis zu 255 Zeichen. |
Geben Sie from oder to an. Wenn Sie keines von beiden angeben, verlangt die API contractaddress und token_id. Bitcoin-Webhooks akzeptieren nur url, from und to. Adressformate werden geprüft, und eine Adresse, die nicht passt, liefert Status 422 mit dem Feldnamen in 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();Ein erfolgreicher Aufruf liefert Status 201 und die ID des Webhooks:
{ "status": 201, "ok": true, "message": "Webhook created", "data": { "webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46" }}Bestehende Webhooks verwalten Sie mit GET /api/v2/{chain}/webhooks zum Auflisten, GET .../webhooks/{id} zum Lesen eines Webhooks, PUT .../webhooks/{id} zum Ändern und DELETE .../webhooks/{id} zum Entfernen. Löschen Sie einen Webhook, sobald die Zahlung eingegangen ist, damit er nicht weiter spätere Überweisungen erfasst. PUT antwortet mit Status 404 und der Meldung Webhook not found, wenn die ID nicht existiert.
Was passiert, wenn eine Zustellung fehlschlägt?
Abschnitt betitelt „Was passiert, wenn eine Zustellung fehlschlägt?“Chaingateway wiederholt eine fehlgeschlagene Zustellung nicht von selbst. Fehlgeschlagene Benachrichtigungen werden gespeichert, und Sie lesen sie und senden sie selbst erneut. Die beiden Endpunkte sind GET /api/v2/{chain}/webhooks/notifications/failed und POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Die Liste wird mit dem Query-Parameter page paginiert.
Jeder Eintrag zeigt die txid, die Ziel-url, die gespeicherte response Ihres Servers und die Anzahl der attempts. Nachdem Sie einen Wiederholungsversuch gestartet haben, verlässt die Benachrichtigung die Liste der fehlgeschlagenen. Schlägt auch der Wiederholungsversuch fehl, kehrt sie in die Liste zurück. GET /api/v2/{chain}/webhooks/notifications listet alle Benachrichtigungen auf, auch die erfolgreichen. Lassen Sie einen kleinen Job in einem Intervall die Liste der fehlgeschlagenen prüfen und wiederholen, was dort steht, und machen Sie den Empfänger idempotent, indem Sie txid als Schlüssel verwenden, damit eine wiederholte Benachrichtigung keinen Schaden anrichtet.
Wie erkenne ich Einzahlungen auf Solana?
Abschnitt betitelt „Wie erkenne ich Einzahlungen auf Solana?“Solana hat keine Webhook-Endpunkte. Die OpenAPI-Datei definiert sie nur für Ethereum, BNB Smart Chain, Polygon, Arbitrum, TRON und Bitcoin. Lesen Sie für Solana in einem festen Intervall das Guthaben der empfangenden Adresse oder listen Sie Transaktionen auf und vergleichen Sie das Ergebnis mit Ihren Aufzeichnungen.
Quellen
Abschnitt betitelt „Quellen“- RFC 9110, HTTP Semantics definiert die POST-Methode und die 2xx-Statuscodes, mit denen ein Empfänger antwortet.
- Ethereum transactions beschreibt die Transaktionsfelder, die in Benachrichtigungen auf den EVM-Chains vorkommen.
- TRON-Transaktionsdokumentation beschreibt die Transaktionstypen hinter den TRON-
type-Werten.