← Blog
10 Min. Lesezeit
|
Veröffentlicht
|
Aktualisiert

Webhooks für Krypto-Einzahlungen: So funktionieren sie

So erkennt ein Webhook eine eingehende Krypto-Einzahlung: Webhook gegen Polling, die Payload-Felder, die HMAC-Signatur und verpasste Benachrichtigungen.

Kapitel
C
Chaingateway Team
Blockchain-Experten

Geprüft von Maurice Sobiera

Ein Webhook ist ein HTTP-Request, den ein Dienst an Ihren Server sendet, wenn ein Ereignis eintritt. Bei Krypto-Einzahlungen ist das Ereignis eine Transaktion, die zu einer überwachten Adresse passt. Chaingateway sendet die Transaktionsdaten an Ihren Endpunkt, und Ihr Code schreibt dem Kunden das Guthaben gut. Das ersetzt wiederholtes Abfragen einer Blockchain-API nach neuen Transaktionen.

Was ist ein Webhook?

Ein Webhook ist ein Callback über HTTP. Sie geben dem Absender eine URL, und der Absender sendet eine POST-Anfrage an diese URL, wenn ein festgelegtes Ereignis eintritt. Der Inhalt der Anfrage ist die Payload. Stellen Sie sich die URL wie eine Telefonnummer vor, die der Absender anruft, sobald etwas passiert.

Webhooks und APIs sind zwei Wege, Daten auszutauschen. Bei einer API holen Sie Daten ab (Pull): Ihr Code fragt in festen Abständen nach und prüft, ob sich etwas geändert hat. Bei einem Webhook liefert der Anbieter Daten (Push): Er meldet sich im Moment des Ereignisses bei Ihnen. Push spart Anfragen und verkürzt die Verzögerung. Pull behält aber eine Rolle, denn ein Webhook sagt nur, dass etwas passiert ist. Wenn Sie den vollständigen Datensatz brauchen oder ihn prüfen wollen, fragen Sie die API ab.

Webhook oder Polling: Was eignet sich für Einzahlungen?

Nutzen Sie Webhooks, um eine Einzahlung schnell zu erfahren, und die API, um sie zu prüfen und abzugleichen. Beides ergänzt sich gut.

AnsatzStärkeSchwäche
Polling der APISie steuern den Zeitpunkt und können nach einem Ausfall weitermachenVerschwendet Anfragen, und die Verzögerung entspricht Ihrem Intervall
WebhookBenachrichtigung kurz nachdem die Transaktion gesehen wurdeEine Benachrichtigung kann verloren gehen, wenn Ihr Endpunkt ausgefallen ist

Bei Chaingateway sind Webhooks für Bitcoin, Ethereum, BNB Smart Chain, Tron, Polygon und Arbitrum verfügbar. Solana hat keine Webhooks, dort fragen Sie Transaktionen ab.

Wie richte ich einen Webhook für Einzahlungen ein?

Legen Sie einen Empfangsendpunkt an und registrieren Sie danach einen Webhook für die Adresse, die Sie überwachen wollen. Der Endpunkt muss aus dem öffentlichen Internet erreichbar sein. Sie müssen keine IP-Adressen von Chaingateway freigeben, weil der Dienst Ihre öffentliche URL wie jeder andere Client aufruft.

Ein Webhook braucht eine url und mindestens eines von from oder to. Die optionalen Filter sind contractaddress, token_id und type. Auf Ethereum ist dieser Typ ETH, ERC20 oder ERC721. Außerdem können Sie eine reference mit bis zu 255 Zeichen setzen, zum Beispiel Ihre Bestellnummer. Diese Anfrage überwacht Einzahlungen eines ERC-20-Tokens (hier der USDT-Contract) an eine Adresse.

Terminal window
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "0x922815dFbEa128eAeaAAa185508fe078bECeFBBE",
"url": "https://example.com/hooks/deposits",
"type": "ERC20",
"contractaddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"reference": "order-1042"
}'

Eine erfolgreiche Anfrage liefert den Status 201 und die Webhook-ID in data.webhook. Legen Sie den Webhook an, bevor der Kunde zahlt. So kann die Zahlung nicht erfolgen, bevor die Überwachung existiert.

Was enthält die Benachrichtigung?

Jede POST-Anfrage enthält die Felder, die Sie brauchen, um die Zahlung einer Bestellung zuzuordnen. Dieses Beispiel stammt aus der Chaingateway-Dokumentation für einen TRC20-Transfer.

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

Die txid identifiziert die Transaktion, und webhook_id zeigt Ihnen, welche Überwachung ausgelöst hat. Speichern Sie die txid mit einem eindeutigen Index. Kommt dieselbe Benachrichtigung zweimal an, schlägt das zweite Einfügen fehl, und Sie überspringen sie.

Wie prüfe ich, ob eine Benachrichtigung echt ist?

Prüfen Sie den Header X-Signature, bevor Sie der Payload vertrauen. Chaingateway berechnet einen HMAC mit SHA-256 über die txid, mit Ihrem persönlichen Secret als Schlüssel, und sendet das Ergebnis Base64-kodiert. HMAC ist in RFC 2104 definiert. Ihr Server wiederholt die Berechnung und vergleicht die beiden Werte mit einem zeitkonstanten Vergleich.

Das persönliche Secret legen Sie in Ihren Profileinstellungen fest. Sobald ein Secret existiert, wird der Header allen ausgehenden Webhooks hinzugefügt. Die Signatur-Dokumentation enthält Prüfcode für Python, Java, PHP und JavaScript.

Wie sieht ein minimaler Empfänger aus?

Ein Empfänger prüft die Signatur, zeichnet das Ereignis genau einmal auf und antwortet schnell. Dieses Express-Beispiel hält gesehene Transaktions-IDs im Speicher, damit es kurz bleibt. Verwenden Sie im Produktivbetrieb eine Datenbanktabelle mit einem eindeutigen Index auf txid.

const crypto = require('crypto');
const express = require('express');
const app = express();
const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => {
const { txid, to, amount } = req.body;
const expected = crypto
.createHmac('sha256', process.env.PERSONAL_SECRET)
.update(txid)
.digest('base64');
const received = req.get('X-Signature') || '';
const valid =
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) {
seen.add(txid);
// credit the order that belongs to the address `to` for `amount`
}
res.sendStatus(200);
});
app.listen(3000);

Testen Sie den Empfänger zuerst im Testnetz. Senden Sie den Header X-Network: testnet beim Anlegen des Webhooks mit und schicken Sie dann einen kleinen Testtransfer an die überwachte Adresse. Die Benachrichtigung sollte mit der txid dieses Transfers eintreffen. Die Dokumentation rät, den Webhook direkt vor der Zahlung anzulegen. Legen Sie ihn deshalb an, wenn Sie die Adresse ausgeben.

Was passiert, wenn mein Server ausfällt?

Die Benachrichtigung wird nicht automatisch erneut gesendet. Nimmt Ihr Endpunkt eine Benachrichtigung nicht an, erscheint sie in der Liste der fehlgeschlagenen Benachrichtigungen unter GET /api/v2/{chain}/webhooks/notifications/failed. Für jeden Eintrag lösen Sie eine neue Zustellung mit POST /api/v2/{chain}/webhooks/notifications/{id}/retry aus. Schlägt der Versuch erneut fehl, bleibt der Eintrag auf der Liste.

Geben Sie einen Erfolgsstatus zurück, sobald Sie das Ereignis gespeichert haben, und erledigen Sie langsame Arbeit danach. RFC 9110 definiert die Klasse 2xx der Statuscodes so, dass die Anfrage empfangen und angenommen wurde. Prüfen Sie die Liste der fehlgeschlagenen Benachrichtigungen regelmäßig. Gleichen Sie Ihre Datensätze mit der API ab, damit eine Lücke nicht unbemerkt bleibt. Der Leitfaden zur Webhook-Zustellung behandelt Duplikate und Reihenfolge ausführlicher.

So entstehen diese Artikel

Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.

C
Chaingateway Team
Blockchain-Experten

Das Chaingateway-Team hat es sich zur Aufgabe gemacht, die Blockchain-Integration für Entwickler weltweit zu vereinfachen.