Blockchain-Webhooks für Einzahlungen
Für Einzahlungsbenachrichtigungen brauchen Sie zwei Teile: einen Empfänger-Endpunkt auf Ihrem Server und einen Webhook, den Sie mit POST /api/v2/{chain}/webhooks erstellen. Passt eine Transaktion zum Filter, sendet Chaingateway einen HTTP-POST-Request mit den Transaktionsdaten an Ihren Endpunkt. Das Tutorial baut beides für TRC20-Einzahlungen auf TRON. Dieselben Schritte gelten für Ethereum, BNB Smart Chain, Polygon, Arbitrum und Bitcoin. Solana hat keine Webhooks.
Lesen Sie zuerst Webhooks, wenn Sie die Konzepte und das Payload-Format kennenlernen möchten. Sie brauchen einen API-Token aus dem Schnellstart.
Wie schreibe ich einen Webhook-Empfänger?
Abschnitt betitelt „Wie schreibe ich einen Webhook-Empfänger?“Ein Empfänger ist ein Server-Endpunkt, der HTTP-POST-Requests mit JSON-Body annimmt und mit dem Status 200 antwortet. Halten Sie den Handler kurz: Payload speichern, antworten und die langsame Arbeit danach in einer Queue oder einem Hintergrundjob erledigen. Die folgenden Beispiele protokollieren die Payload und bestätigen sie.
const express = require('express');const app = express();const port = 3000;
app.use(express.json());
app.post('/webhook', (req, res) => { console.log('Received webhook:', req.body); res.status(200).send('Webhook received');});
app.listen(port, () => { console.log(`Webhook receiver listening at http://localhost:${port}`);});from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])def webhook(): data = request.get_json() print('Received webhook:', data) return jsonify({'status': 'Webhook received'}), 200
if __name__ == '__main__': app.run(port=3000)<?phpif ($_SERVER['REQUEST_METHOD'] === 'POST') { $data = file_get_contents('php://input'); $json = json_decode($data, true); file_put_contents('php://stderr', print_r($json, TRUE)); http_response_code(200); echo json_encode(['status' => 'Webhook received']);}<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class WebhookController extends Controller{ // Register the route in routes/api.php: // Route::post('/webhook', [WebhookController::class, 'handleWebhook']); public function handleWebhook(Request $request) { $data = $request->all(); file_put_contents('php://stderr', print_r($data, TRUE)); return response()->json(['status' => 'Webhook received'], 200); }}Chaingateway erreicht nur eine öffentliche URL. Machen Sie während der Entwicklung Ihren lokalen Port über einen Tunnel verfügbar und nutzen Sie die HTTPS-Adresse des Tunnels als url des Webhooks. Prüfen Sie die Signatur jeder Anfrage, bevor Sie darauf reagieren, wie Webhook-Sicherheit beschreibt.
Wie abonniere ich ein Blockchain-Ereignis?
Abschnitt betitelt „Wie abonniere ich ein Blockchain-Ereignis?“Senden Sie POST /api/v2/tron/webhooks mit der url Ihres Empfängers und einem Filter. Der Filter bestimmt, welche Transaktionen eine Benachrichtigung auslösen.
url(Pflicht): die Adresse Ihres Empfängers. Sie muss eine gültige URL sein.fromundto: die Adresse von Absender und Empfänger im Tron-Format. Mindestens eines davon ist Pflicht, es sei denn, Sie geben stattdessencontractaddressundtoken_idan.contractaddress: der Contract des Tokens, der verfolgt werden soll.token_id: eine NFT-Token-ID.type: einer vonTRX,TRC10,TRC20,TRC721.reference: Ihre eigene Bezeichnung mit bis zu 255 Zeichen, zum Beispiel eine Bestellnummer.
Das Beispiel überwacht TRC20-Transfers eines Tokens an eine Einzahlungsadresse.
curl --request POST \ --url https://app.chaingateway.io/api/v2/tron/webhooks \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_TOKEN' \ --data '{ "url": "https://example.com/webhook", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "type": "TRC20", "reference": "order-1042"}'import requests
url = "https://app.chaingateway.io/api/v2/tron/webhooks"payload = { "url": "https://example.com/webhook", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "type": "TRC20", "reference": "order-1042"}headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'}
response = requests.post(url, json=payload, headers=headers)print(response.json())const axios = require('axios');
const url = 'https://app.chaingateway.io/api/v2/tron/webhooks';const payload = { url: 'https://example.com/webhook', to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', type: 'TRC20', reference: 'order-1042'};const headers = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_TOKEN'};
axios.post(url, payload, { headers }) .then(response => { console.log(response.data); }) .catch(error => { console.error(error.response?.data ?? error); });<?phprequire 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();$response = $client->post('https://app.chaingateway.io/api/v2/tron/webhooks', [ 'headers' => [ 'Accept' => 'application/json', 'Authorization' => 'Bearer YOUR_API_TOKEN', ], 'json' => [ 'url' => 'https://example.com/webhook', 'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp', 'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'type' => 'TRC20', 'reference' => 'order-1042' ]]);
echo $response->getBody();Die Antwort hat den Status 201 und enthält die ID des Webhooks in data.webhook. Bewahren Sie die ID auf, denn Sie brauchen sie, um den Webhook zu ändern oder zu löschen.
{ "status": 201, "ok": true, "message": "Webhook created", "data": { "webhook": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46" }}Auf anderen Chains ändern sich der Pfad und die type-Werte. Ethereum und Arbitrum akzeptieren ETH, ERC20 und ERC721, Polygon akzeptiert MATIC, ERC20 und ERC721, BNB Smart Chain akzeptiert BNB, BEP20 und BEP721, und Bitcoin nimmt nur url, from und to. Adressen auf den EVM-Chains müssen 0x gefolgt von 40 Hex-Zeichen entsprechen. Um auf einem Testnetz zu testen, fügen Sie der Anfrage zum Erstellen den Header X-Network: testnet hinzu.
Wie teste ich den Empfänger, bevor eine echte Einzahlung eintrifft?
Abschnitt betitelt „Wie teste ich den Empfänger, bevor eine echte Einzahlung eintrifft?“Senden Sie mit curl eine Beispielbenachrichtigung an Ihren eigenen Endpunkt. Der Body unten hat dieselben Felder wie eine echte Benachrichtigung. Protokolliert Ihr Empfänger sie und antwortet mit 200, funktioniert der Endpunkt. Senden Sie danach einen kleinen Testnet-Transfer an die überwachte Adresse, um das echte Ereignis zu sehen.
curl --request POST \ --url https://example.com/webhook \ --header 'Content-Type: application/json' \ --data '{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9b2b4dcc-1479-4bcd-9b8a-015673e80f46", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "blocknumber": "65542464", "datetime": "2024-09-25 14:48:27", "tokenid": null, "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}'Was mache ich mit fehlgeschlagenen Zustellungen und alten Webhooks?
Abschnitt betitelt „Was mache ich mit fehlgeschlagenen Zustellungen und alten Webhooks?“Chaingateway wiederholt fehlgeschlagene Zustellungen nicht automatisch. GET /api/v2/tron/webhooks/notifications/failed listet sie auf, und POST /api/v2/tron/webhooks/notifications/{id}/retry sendet eine davon erneut. Mit GET /api/v2/tron/webhooks listen Sie Ihre Webhooks auf, mit PUT /api/v2/tron/webhooks/{id} ändern Sie einen und mit DELETE /api/v2/tron/webhooks/{id} entfernen Sie ihn. Löschen Sie einen Webhook, sobald er seine Aufgabe erfüllt hat, zum Beispiel nachdem die Zahlung für eine Bestellung eingetroffen ist.
Wichtige Informationen
Abschnitt betitelt „Wichtige Informationen“- Der Empfänger muss öffentlich erreichbar sein und HTTP-POST-Requests annehmen.
- Prüfen Sie Herkunft und Integrität jeder Anfrage mit dem Header
X-Signature. - Machen Sie den Empfänger idempotent. Erkennen Sie mit der
txid, ob Sie eine Benachrichtigung bereits verarbeitet haben. - Bewahren Sie Ihren API-Token in einem Secrets-Store auf, nicht im Quellcode des Empfängers.
Quellen
Abschnitt betitelt „Quellen“- RFC 9110, HTTP Semantics definiert die POST-Methode und die Statuscodes, die der Empfänger verwendet.
- TRON TRC20 protocol interface definiert die Token-Ereignisse hinter TRC20-Benachrichtigungen.
- Ethereum token standard EIP-20 definiert dasselbe für ERC-20 auf den EVM-Chains.