Zum Inhalt springen

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.

Webhook-Lebenszyklus: Webhook mit Filter erstellen, eine passende Transaktion löst ein POST an Ihre URL aus, Ihr Server antwortet 200, fehlgeschlagene Zustellungen werden aufgelistet und auf Anfrage erneut gesendet Webhook erstellen POST /api/v2/{chain}/webhooks mit url undeinem Filter Eine Transaktion passt zum Filter Chaingateway sendet die Benachrichtigung perPOST an Ihre url Ihr Empfänger antwortet 200 und verarbeitet den Payload Zustellung fehlgeschlagen? GET .../webhooks/notifications/failed, dannPOST .../notifications/{id}/retry
Fehlgeschlagene Benachrichtigungen werden nicht automatisch wiederholt. Sie listen sie auf und senden sie selbst erneut.

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:

  1. Bauen Sie einen Empfängerendpunkt, den Chaingateway erreichen kann.
  2. Erstellen Sie einen Webhook, der auf den Empfänger zeigt.
  3. Warten Sie auf ein passendes Blockchain-Ereignis.
  4. 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()

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.

FeldBedeutung
urlErforderlich. Die vollständige URL Ihres Empfängers, einschließlich Pfad.
fromAbsenderadresse, die beobachtet wird.
toEmpfängeradresse, die beobachtet wird.
contractaddressContract-Adresse eines Tokens, den Sie verfolgen möchten. Auf Bitcoin nicht verfügbar.
token_idNFT-Token-ID.
typeAsset-Typ. Ethereum und Arbitrum: ETH, ERC20, ERC721. Polygon: MATIC, ERC20, ERC721. BNB Smart Chain: BNB, BEP20, BEP721. TRON: TRX, TRC10, TRC20, TRC721.
referenceIhre 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.

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

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.

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.

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.