Polygon Webhooks: On-Chain-Events in Echtzeit erhalten – ohne Polling

Polygon-Webhooks sind HTTP-Callbacks, die ein Dienst an Ihren Server sendet, wenn etwas in der Polygon-Chain passiert, beispielsweise wenn eine USDC-Einzahlung an einer Ihrer Adressen eingeht. Sie registrieren eine URL, der Anbieter überwacht die Chain, und Ihr Backend erhält einen signierten POST, anstatt alle paar Sekunden einen RPC-Node abzufragen. Dieser Leitfaden behandelt, wie das bei Polygon PoS funktioniert, was schiefgehen kann und wie Sie einen Handler bauen, dem Sie Geld anvertrauen können.

TL;DR

• Ein Webhook ersetzt Polling: Der Anbieter überwacht Polygon und pusht Ereignisse (Einzahlungen, Transfers, Token-Bewegungen) an Ihren Endpunkt.
• Polygon-Blöcke erscheinen etwa alle 2 Sekunden, daher sind Ereignisse schnell, aber Sie benötigen trotzdem eine Bestätigungsrichtlinie, bevor Sie Gelder gutschreiben.
• Behandeln Sie jede Zustellung als potenziell dupliziert, verspätet oder out-of-order: Verifizieren Sie die Signatur, speichern Sie die Ereignis-ID und verarbeiten Sie idempotent.
• Bestätigen Sie schnell, erledigen Sie die Arbeit in einer Queue und gleichen Sie planmäßig gegen die Chain ab.
• Chaingateway Webhooks liefern HMAC-signierte, vordekodierte Polygon-Ereignisse, sodass Sie auf das Betreiben von Nodes und das Parsen von Logs verzichten können.

Inhaltsverzeichnis

• Was ein Polygon-Webhook tatsächlich ist
• Warum Webhooks auf Polygon Polling schlagen
• Bestätigungen, Finalität und Reorgs bei Polygon PoS
• Wie ein sicherer Polygon-Webhook-Handler aussieht
• Tokens und Edge Cases auf Polygon
• Selbst bauen oder einheitliche API nutzen
• Unsere Perspektive: Webhooks sind ein Ledger-Problem, kein Benachrichtigungsproblem
• Polygon-Webhooks mit Chaingateway erhalten
• Eine Start-Checkliste
• FAQ
• Quellen

Was ein Polygon-Webhook tatsächlich ist

Polygon PoS ist eine EVM-Chain. Jeder ERC-20-Transfer, sei es USDC, USDT oder ein von Ihnen selbst herausgegebenes Token, erzeugt ein Transfer-Log. Native POL bewegt sich als einfacher Werttransfer ganz ohne Log. Raw RPC liefert beides in unterschiedlichen Formen: Logs für Tokens, Transaktions- und Trace-Daten für native Coins. Wenn Sie wissen wollen, dass ein Kunde gezahlt hat, müssen Sie dieses Bild selbst zusammenfügen.

Ein Webhook-Dienst übernimmt die Zusammenstellung. Sie abonnieren eine Adresse (oder einen Satz davon), und wenn ein passendes Ereignis eintritt, sendet der Dienst eine JSON-Payload an Ihre URL. Eine gute Payload teilt Ihnen die Chain, den Transaktions-Hash, Absender, Empfänger, Token, Betrag in lesbaren Einheiten, Blocknummer und eine eindeutige Ereignis-ID mit. Das ist der Unterschied zwischen „hier ist ein Log mit Hex-Topics“ und „Kunde 4812 hat 250 USDC gezahlt“.

Drei Dinge, die unter diesem Stichwort gesucht werden, sind eigentlich drei verschiedene Werkzeuge:

• Adress- und Zahlungs-Webhooks: Benachrichtigen Sie mich, wenn Gelder an diese Adressen eingehen. Das ist das, was Zahlungsflüsse benötigen.
• Vertragsereignis-Webhooks: Benachrichtigen Sie mich, wenn ein bestimmter Smart Contract ein bestimmtes Ereignis ausstößt. Das ist das, was dApp-Backends und Analysen benötigen.
• Protokoll-Webhooks: Benachrichtigungen von einem Polygon-Produkt selbst über seine eigenen Operationen. Diese gehören in die Dokumentation jenes Produkts, nicht in einen allgemeinen Chain-Listener.

Dieser Artikel behandelt die erste Art, mit Anmerkungen zur zweiten.

Warum Webhooks Polling auf Polygon schlagen

Polygon erzeugt etwa alle zwei Sekunden einen Block, laut dieser Referenz zur Bestätigungszeit. Wenn Sie einen RPC-Endpunkt nach neuen Blöcken abfragen und Logs selbst filtern, stehen Sie vor einem Kompromiss ohne gute Lösung:

• Alle paar Sekunden abfragen und Sie verbrauchen Rate-Limits und zahlen für meist leere Antworten.
• Jede Minute abfragen und Ihr Kunde starrt nach der Zahlung eine Minute lang auf einen Spinner.
• Nach einem Neustart einen Bereich verpassen und Sie haben eine stille Lücke in Ihrem Ledger.

Webhooks kehren dies um. Der Anbieter übernimmt das Überwachen, die Wiederholungsversuche und die Block-Buchführung. Ihre Aufgabe schrumpft auf das Betreiben eines Endpunkts, der Ereignisse korrekt verarbeitet. Wir gehen in unserem Beitrag zu Webhooks vs. WebSockets tiefer auf die architektonischen Kompromisse ein, einschließlich des von uns empfohlenen Ingest-, Queue- und Fan-out-Musters.

Bestätigungen, Finalität und Reorgs bei Polygon PoS

Ein Webhook, der beim ersten Ansehen einer Transaktion auslöst, ist schnell. Er ist nicht final. Bevor Sie Waren freigeben oder ein Guthaben gutschreiben, entscheiden Sie, wie viele Blöcke Sie warten.

Polygon PoS bestätigt schnell. Ein Tracker gibt die typische erste Bestätigung mit 1 bis 5 Sekunden an und merkt an, dass Börsen üblicherweise 128 Blöcke warten, also etwa 4 bis 5 Minuten, um sich gegen Reorganisationen abzusichern. Eine andere Quelle berichtet, dass das Heimdall v2-Upgrade im Juli 2025 die harte Finalität auf etwa 5 Sekunden reduzierte. Die Praktiken unterscheiden sich zwischen Börsen und Tools, und Netzwerk-Upgrades ändern die Zahlen, daher prüfen Sie die aktuelle Polygon-Dokumentation, bevor Sie einen Schwellenwert in der Produktion festlegen.

Ein praktischer Weg zur Wahl besteht darin, die Richtlinie an den gefährdeten Wert zu koppeln:

Diese Tabelle ist unsere empfohlene Richtlinie, keine Polygon-Regel. Wählen Sie Zahlen, die Ihrer eigenen Risikotoleranz entsprechen, und dokumentieren Sie diese.

In Ihrem Datenmodell weisen Sie jeder eingehenden Zahlung einen Status wie detected, confirming und final zu. Zeigen Sie dem Kunden den ersten Zustand sofort an und bewegen Sie Gelder erst beim letzten. Wenn Ihr Anbieter separate Events sendet, während sich Bestätigungen ansammeln, nutzen Sie diese. Andernfalls speichern Sie die Blocknummer vom ersten Event und vergleichen Sie sie per Timer mit dem Chain Head.

Wie ein sicherer Polygon-Webhook-Handler aussieht

Die Polygon-Entwicklerdokumente enthalten eine Anleitung zum Empfang von Webhooks für eines ihrer eigenen Produkte, und die dort vermittelten Prinzipien gelten für jede Webhook-Integration: Lieferung verifizieren und anwenden, ohne Doppelverarbeitung oder Anwendung veralteter Zustände. Hier ist dieselbe Disziplin für Chain-Events.

1. Signatur vor allem anderen verifizieren

Jeder, der Ihre URL findet, kann dorthin POSTen. Ohne Verifizierung kann ein Angreifer ein gefälschtes „250 USDC erhalten“ senden und mit Ihrem Produkt verschwinden. Unsignierte oder fehlerhaft signierte Requests mit 401 ablehnen und den Body nicht weiter parsen.

Chaingateway signiert Anfragen mit HMAC. Sie berechnen die Signatur über den rohen Anfragekörper mit Ihrem gemeinsamen Geheimnis und vergleichen sie mittels eines konstantzeitigen Vergleichs. Verwenden Sie die rohen Bytes, kein re-serialisiertes JSON-Objekt, da eine Re-Serialisierung Whitespaces und die Schlüsselreihenfolge ändert und den Abgleich ungültig macht. Unser Beitrag zu einem neuen Feature zur Erhöhung der Webhook-Sicherheit erläutert die Verifizierungsoptionen im Detail.

Für den umfassenderen Überblick zum Schutz von Schlüsseln, Endpunkten und operativen Prozessen rund um digitale Assets ist diese Übersicht zu digitaler Asset-Sicherheit und Risikomanagement eine nützliche Lektüre für die nicht-technische Seite des Problems.

2. Verarbeitung idempotent gestalten

Gehen Sie von mindestens einmaliger Zustellung aus. Ein Timeout auf Ihrer Seite veranlasst den Absender zu einem erneuten Versuch, und ein erneuter Versuch kann eintreffen, nachdem Sie die erste Kopie bereits verarbeitet haben. Speichern Sie einen eindeutigen Schlüssel pro Ereignis, idealerweise den Transaktionshash plus Log-Index oder die Ereignis-ID, die der Anbieter liefert. Legen Sie eine Unique-Constraint darauf in Ihrer Datenbank an:

INSERT INTO processed_events (event_key, received_at)
VALUES ($1, now())
ON CONFLICT (event_key) DO NOTHING;

Wenn der Insert null Zeilen betrifft, haben Sie dieses Ereignis bereits gesehen. Geben Sie 200 zurück und stoppen Sie. Führen Sie den Insert und die Kontostandsaktualisierung in derselben Datenbanktransaktion aus, damit ein Absturz nicht das eine ohne das andere hinterlässt.

3. Schnell bestätigen, später arbeiten

Geben Sie einen 2xx-Status zurück, sobald das Ereignis verifiziert und sicher gespeichert ist. Führen Sie die langsame Arbeit, wie das Versenden von E-Mails an den Kunden, das Aktualisieren von Ledgern und das Aufrufen anderer Dienste, über eine Warteschlange aus. Wenn Ihr Handler dreißig Sekunden benötigt, wird der Absender einen Timeout erleiden und erneut versuchen, und Sie werden Duplikate debuggen.

4. Der Reihenfolge nicht vertrauen

Zwei Ereignisse über dieselbe Zahlung können in beliebiger Reihenfolge eintreffen, beispielsweise ein Bestätigungs-Update vor der ursprünglichen Erkennung. Vergleichen Sie Blocknummern oder Sequenzfelder und ignorieren Sie alles, was älter ist als der Zustand, den Sie bereits halten. Lassen Sie niemals ein spätes “detected”-Ereignis einen “final”-Datensatz überschreiben.

5. Validieren, was die Payload behauptet

Prüfen Sie, ob der Empfänger eine Adresse ist, die Sie ausgegeben haben, ob der Token-Vertrag einer ist, den Sie akzeptieren, und ob der Betrag der Rechnung entspricht. Dies ist auf Polygon wichtiger, als viele erwarten, da jeder einen Token namens “USDC” bereitstellen und an Ihre Adresse senden kann. Vergleichen Sie Vertragsadressen, niemals Symbole.

6. Für Ausfälle planen

Ihr Server wird irgendwann ausfallen. Entscheiden Sie im Voraus, wie Sie sich erholen:

• Nutzen Sie einen Anbieter, der fehlgeschlagene Zustellungen wiederholt.
• Führen Sie einen Abgleichsjob aus, beispielsweise alle paar Minuten, der Kontostände oder kürzliche Transfers für Ihre Adressen prüft und alles markiert, das Ihr Webhook-Log nie gesehen hat.
• Alarmieren Sie, wenn über einen ungewöhnlich langen Zeitraum keine Ereignisse eintreffen. Auf einem stark frequentierten System ist Stille ein Signal.

Webhooks sind Ihr schneller Pfad. Der Abgleich ist Ihr Sicherheitsnetz. Betreiben Sie beides.

Tokens und Edge Cases auf Polygon

USDC und USDT. Stablecoin-Zahlungen sind der Hauptgrund, warum Entwickler Polygon-Webhooks einrichten, da die Gebühren niedrig und die Abwicklung schnell ist. Stellen Sie sicher, dass Sie wissen, welchen Vertrag jeder Stablecoin auf Polygon verwendet, und setzen Sie diese Adressen auf die Whitelist, wie oben beschrieben.

Natives POL. Native Transfers emittieren keine Token-Logs, sodass ein Listener, der nur auf Transfer-Ereignisse basiert, diese verpassen wird. Bestätigen Sie, dass Ihr Anbieter auch native Coin-Bewegungen meldet, falls Sie POL akzeptieren möchten.

Vertrags-zu-Adresse-Zahlungen. Eine Zahlung kann von einer Smart-Contract-Wallet oder einer Multisig stammen, nicht von einem einfachen Konto. Gehen Sie nicht davon aus, dass der Absender der Kunde ist. Verknüpfen Sie Zahlungen mit Kunden über die Empfangsadresse, die Sie für sie generiert haben, nicht über den Absender.

Fehlgeschlagene und reverted Transaktionen. Eine reverted Transaktion verbraucht Gas, bewegt aber nichts. Reagieren Sie nur auf Events, die erfolgreiche Transfers darstellen.

Dust- und Spam-Token. Unaufgeforderte Token tauchen regelmäßig in Adressen auf. Ignorieren Sie Verträge, die Sie nicht auf die Whitelist gesetzt haben.

Selbst entwickeln oder eine einheitliche API nutzen

Es gibt drei realistische Wege zu Polygon-Event-Benachrichtigungen:

1. Eigenen Node und Listener betreiben. Maximale Kontrolle, aber Sie sind für Node-Upgrades, Speicherwachstum, Log-Dekodierung, Reorg-Handling und Uptime verantwortlich. Sinnvoll, wenn Chain-Infrastruktur Ihr Produkt ist.
2. Einen allgemeinen Node- oder Datenanbieter nutzen und das Filtern selbst schreiben. Weniger operativer Aufwand, aber Sie bauen weiterhin Subscriptions, Retries, Dekodierung und die Signatur-Ebene.
3. Eine payments-fokussierte API nutzen, die dekodierte, signierte Events liefert. Sie schreiben den Endpunkt und die Business-Logik, nichts weiter.

Für ein Team, das Krypto in seinem Produkt akzeptieren oder senden möchte, führt der dritte Weg meist am schnellsten in die Produktion. Wir vergleichen die Optionen ausführlicher in Blockchain APIs im Vergleich: 6 Typen und wann man welchen nutzt.

Unsere Perspektive: Webhooks sind ein Ledger-Problem, kein Benachrichtigungsproblem

Die meisten Integrationsfehler, die wir sehen, betreffen nicht den Empfang der HTTP-Anfrage. Sie betreffen das, was danach passiert. Teams behandeln einen Webhook als Auslöser („Zahlung eingegangen, versenden“), obwohl er eigentlich nur ein Input für ein Ledger ist, das unter Retries, Reorgs und Neustarts korrekt bleiben muss.

Das prägt, wie wir Chaingateway bauen. Wir liefern vordekodierte Events, sodass Ihr Code einen Betrag und einen Token liest, keine hex-kodierten Log-Topics. Wir signieren jede Anfrage mit HMAC, damit Ihr Endpunkt Fälschungen ablehnen kann. Und wir decken Polygon neben Ethereum, Tron, Bitcoin, Solana, BNB Chain und Arbitrum über eine REST-API ab, sodass Ihre Handler-Logik gleich bleibt, wenn Sie eine zweite Chain hinzufügen.

Unser Rat: Schreiben Sie Ihren Idempotenz- und Abgleichscode zuerst, bevor Sie den Happy Path implementieren. Wenn Sie dasselbe Event zehnmal wiederholen und drei Events vertauschen können und am Ende der richtige Saldo steht, ist der Rest einfach. Unser Artikel zum automatischen Verarbeiten von Deposits mit Webhooks führt diesen Flow Ende-zu-Ende durch.

— Bitblade

Polygon-Webhooks mit Chaingateway erhalten

Mit Chaingateway Webhooks erstellen Sie Wallets oder registrieren Adressen über die API, abonnieren Zahlungsereignisse und erhalten signierte Benachrichtigungen an Ihrem Endpunkt. Die Polygon API Seite behandelt das Senden und Empfangen von USDC und USDT auf Polygon, und die Blockchain API deckt Wallets, Transfers, dekodierte Transaktionsdaten und Gas-Schätzungen über unterstützte Chains ab.

Pläne werden auf der Preisseite veröffentlicht:

Der kostenpflichtige Zugriff beginnt nach einer kostenlosen Testphase, sodass Sie den vollständigen Ablauf testen können, einschließlich Signaturprüfungen und Duplikatbehandlung, bevor Sie sich festlegen.

Eine Start-Checkliste

Bevor Sie Produktionsverkehr an Ihren Endpunkt leiten, arbeiten Sie dies ab:

• Nur HTTPS, mit einem gültigen Zertifikat.
• Signatur auf dem Roh-Body verifiziert, Vergleich in konstanter Zeit.
• Eindeutige Beschränkung für den Ereignis-Schlüssel.
• 2xx innerhalb weniger Sekunden zurückgegeben, Arbeit in eine Warteschlange verschoben.
• Vertragsadressen auf einer Whitelist, Beträge und Empfänger validiert.
• Statusmodell mit ausstehenden und endgültigen Zuständen sowie einem dokumentierten Bestätigungsschwellenwert.
• Abgleichsjob und ein Alarm für fehlende Ereignisse.
• Geheimnisse außerhalb des Repositories gespeichert und ohne Ausfallzeiten rotierbar.
• Ein Replay-Test: Senden Sie dasselbe Ereignis mehrmals und in falscher Reihenfolge in der Staging-Umgebung.

Quellen

• Polygon Confirmation Time Referenz
• USDT Bestätigungszeit nach Netzwerk
• Polygon Entwickler-Dokumentation

Empfohlen

• Blockchain Webhooks & Event Notifications
• Webhooks vs WebSockets für Entwickler: Ingest, Queue, Fan Out Pattern
• Die Verwendung von Webhooks zur automatischen Verarbeitung von Einzahlungen