Zum Inhalt springen

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.

Schritte des Tutorials: Empfänger schreiben, aus dem Internet erreichbar machen, Webhook erstellen, Test-Payload senden, fehlgeschlagene Zustellungen behandeln 1. Empfänger schreiben POST-Endpunkt, der 200 antwortet 2. Erreichbar machen öffentliche HTTPS-URL 3. Webhook erstellen POST /api/v2/tron/webhooks mit url und Filter 4. Mit Payload testen curl gegen Ihren eigenen Empfänger 5. Fehler behandeln fehlgeschlagene Benachrichtigungen auflisten,erneut senden
Die Schritte 1 und 2 kommen vor Schritt 3, weil die URL beim ersten Ereignis funktionieren muss.

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}`);
});

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.

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.
  • from und to: die Adresse von Absender und Empfänger im Tron-Format. Mindestens eines davon ist Pflicht, es sei denn, Sie geben stattdessen contractaddress und token_id an.
  • contractaddress: der Contract des Tokens, der verfolgt werden soll.
  • token_id: eine NFT-Token-ID.
  • type: einer von TRX, 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.

Terminal-Fenster
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"
}'

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.

Terminal-Fenster
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.

  • 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.