Webhook Polygon: Ricevi Eventi On-Chain in Tempo Reale Senza Polling

I webhook di Polygon sono callback HTTP che un servizio invia al suo server quando accade qualcosa sulla chain di Polygon, ad esempio un deposito di USDC che arriva a uno dei suoi indirizzi. Lei registra un URL, il provider monitora la chain e il suo backend riceve una POST firmata invece di interrogare un nodo RPC ogni pochi secondi. Questa guida spiega come funziona su Polygon PoS, cosa può andare storto e come costruire un handler di cui ci si può fidare con i soldi.

TL;DR

• Un webhook sostituisce il polling: il provider monitora Polygon e invia gli eventi (depositi, trasferimenti, movimenti di token) al suo endpoint.
• I blocchi di Polygon arrivano circa ogni 2 secondi, quindi gli eventi sono veloci, ma serve comunque una politica di conferma prima di accreditare i fondi.
• Tratti ogni consegna come potenzialmente duplicata, in ritardo o fuori ordine: verifichi la firma, memorizzi l’ID dell’evento e processi in modo idempotente.
• Risponda velocemente, faccia il lavoro in una coda e riconcili con la chain secondo una pianificazione.
• I Webhook di Chaingateway consegnano eventi Polygon pre-decodificati e firmati con HMAC, così Lei evita di gestire nodi e parsare log.

Indice

• Cos’è effettivamente un webhook di Polygon
• Perché i webhook battono il polling su Polygon
• Conferme, finalità e reorg su Polygon PoS
• Come si presenta un handler di webhook Polygon sicuro
• Token ed edge case su Polygon
• Costruirlo da sé o usare un’API unificata
• La nostra prospettiva: i webhook sono un problema di ledger, non di notifica
• Ottenere i webhook di Polygon con Chaingateway
• Una checklist per il lancio
• FAQ
• Fonti

Cos’è effettivamente un webhook di Polygon

Polygon PoS è una chain EVM. Ogni trasferimento ERC-20, che sia USDC, USDT o un token emesso da Lei, emette un log Transfer. Il POL nativo si muove come un semplice trasferimento di valore senza alcun log. L’RPC grezzo Le dà entrambi in forme diverse: log per i token, dati di transazione e trace per le coin native. Se vuole sapere che un cliente ha pagato, deve assemblare da sé quel quadro.

Un servizio di webhook fa l’assemblaggio. Lei si abbona a un indirizzo (o a un insieme di essi) e, quando si verifica un evento corrispondente, il servizio invia un payload JSON al suo URL. Un buon payload Le dice la chain, l’hash della transazione, mittente, destinatario, token, importo in unità umane, numero di blocco e un identificativo univoco dell’evento. Questa è la differenza tra “ecco un log con topic esadecimali” e “il cliente 4812 ha pagato 250 USDC”.

Tre cose che le persone cercano con questa parola chiave sono in realtà tre strumenti diversi:

• Webhook per indirizzi e pagamenti: mi avvisi quando arrivano fondi su questi indirizzi. È ciò che serve ai flussi di pagamento.
• Webhook per eventi di contratto: mi avvisi quando un dato smart contract emette un dato evento. È ciò che serve ai backend delle dApp e all’analisi.
• Webhook a livello di protocollo: notifiche da un prodotto Polygon stesso sulle sue operazioni. Quelle appartengono alla documentazione di quel prodotto, non a un listener generico di chain.

Questo articolo riguarda il primo tipo, con note sul secondo.

Perché i webhook battono il polling su Polygon

Polygon produce un blocco circa ogni due secondi, secondo questo riferimento sui tempi di conferma. Se esegue il polling di un endpoint RPC per i nuovi blocchi e filtra i log da solo, si trova di fronte a un compromesso senza una buona risposta:

• Eseguire il polling ogni pochi secondi e brucia i limiti di frequenza e paga per risposte per lo più vuote.
• Eseguire il polling ogni minuto e il suo cliente fissa uno spinner per un minuto dopo aver pagato.
• Perdere un intervallo dopo un riavvio e ha un buco silenzioso nel suo registro.

I webhook ribaltano la situazione. Il provider si occupa della sorveglianza, dei tentativi e della contabilità dei blocchi. Il suo compito si riduce a gestire un endpoint che gestisce gli eventi correttamente. Approfondiamo i compromessi architetturali nel nostro post su webhook vs WebSocket, incluso il pattern di ingestione, coda e fan-out che consigliamo.

Conferme, finalità e riorganizzazioni su Polygon PoS

Un webhook che scatta alla prima vista di una transazione è veloce. Non è definitivo. Prima di rilasciare beni o accreditare un saldo, decida quanti blocchi attendere.

Polygon PoS conferma rapidamente. Un tracker indica la prima conferma tipica a 1-5 secondi, e nota che gli exchange comunemente attendono 128 blocchi, circa 4-5 minuti, per proteggersi dalle riorganizzazioni. Un’altra fonte riporta che l’aggiornamento Heimdall v2 di luglio 2025 ha ridotto la finalità dura a circa 5 secondi. Le pratiche differiscono tra exchange e strumenti, e gli aggiornamenti di rete cambiano i numeri, quindi controlli l’attuale documentazione di Polygon prima di fissare una soglia in produzione.

Un modo pratico per scegliere è legare la politica al valore a rischio:

Questa tabella è la nostra politica suggerita, non una regola di Polygon. Scelga numeri che corrispondano alla sua tolleranza al rischio e li scriva.

Nel suo modello dati, dia a ogni pagamento in entrata uno stato come detected, confirming e final. Mostri al cliente il primo stato immediatamente e sposti i fondi solo sull’ultimo. Se il suo provider invia eventi separati man mano che le conferme si accumulano, li usi. Se no, memorizzi il numero di blocco dal primo evento e lo confronti con la testa della catena su un timer.

Come appare un gestore webhook Polygon sicuro

La documentazione per sviluppatori di Polygon include una guida sulla ricezione dei webhook per uno dei loro prodotti, e i principi che insegna si applicano a ogni integrazione webhook: verifichi la consegna e la applichi senza doppia elaborazione o applicazione di stato obsoleto. Ecco la stessa disciplina per gli eventi on-chain.

1. Verifichi la firma prima di qualsiasi altra cosa

Chiunque trovi il suo URL può fare POST su di esso. Senza verifica, un attaccante può inviare un falso “250 USDC ricevuti” e andarsene con il suo prodotto. Rifiuti le richieste non firmate o firmate male con un 401 e non analizzi ulteriormente il corpo.

Chaingateway firma le richieste con HMAC. Lei calcola la firma sul corpo grezzo della richiesta con il suo segreto condiviso e la confronta utilizzando un confronto a tempo costante. Utilizzi i byte grezzi, non un oggetto JSON ri-serializzato, perché la ri-serializzazione modifica gli spazi bianchi e l’ordine delle chiavi e interrompe la corrispondenza. Il nostro post su una nuova funzionalità per migliorare la sicurezza dei webhook spiega le opzioni di verifica in dettaglio.

Per una visione d’insieme più ampia sulla protezione di chiavi, endpoint e processi operativi attorno agli asset digitali, questa panoramica sulla sicurezza e gestione del rischio degli asset digitali è una lettura utile per l’aspetto non tecnico del problema.

2. Rendere l’elaborazione idempotente

Assuma una consegna almeno una volta. Un timeout dalla sua parte fa sì che il mittente ritenti, e un nuovo tentativo può arrivare dopo che lei ha già elaborato la prima copia. Memorizzi una chiave univoca per evento, idealmente l’hash della transazione più l’indice del log, o l’ID evento che il fornitore fornisce. Imponga un vincolo univoco su di essa nel suo database:

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

Se l’inserimento non interessa alcuna riga, lei ha già visto questo evento. Restituisca 200 e si fermi. Esegua l’inserimento e l’aggiornamento del saldo nella stessa transazione del database in modo che un crash non possa lasciare l’uno senza l’altro.

3. Confermare velocemente, lavorare dopo

Restituisca un 2xx non appena l’evento è verificato e memorizzato in modo sicuro. Esegua il lavoro lento, come l’invio di email al cliente, l’aggiornamento dei registri e la chiamata ad altri servizi, da una coda. Se il suo gestore impiega trenta secondi, il mittente andrà in timeout e ritenterà, e lei si troverà a fare il debug dei duplicati.

4. Non fidarsi dell’ordine

Due eventi sullo stesso pagamento possono arrivare in qualsiasi ordine, ad esempio un aggiornamento di conferma prima del rilevamento originale. Confronti i numeri di blocco o i campi di sequenza e ignori qualsiasi cosa più vecchia dello stato che già detiene. Non permetta mai che un evento “rilevato” tardivo sovrascriva un record “finale”.

5. Validare ciò che il payload dichiara

Verifichi che il destinatario sia un indirizzo che lei ha emesso, che il contratto del token sia uno che accetta, e che l’importo corrisponda alla fattura. Questo è importante su Polygon più di quanto ci si aspetti, perché chiunque può distribuire un token chiamato “USDC” e inviarlo al suo indirizzo. Confronti gli indirizzi dei contratti, mai i simboli.

6. Pianificare per il fallimento

Il suo server sarà inattivo ad un certo punto. Decida in anticipo come recuperare:

• Utilizzi un fornitore che ritenta le consegne fallite.
• Esegua un job di riconciliazione, ad esempio ogni pochi minuti, che controlli i saldi o i trasferimenti recenti per i suoi indirizzi e segnali qualsiasi cosa il suo log dei webhook non abbia mai visto.
• Avvisi quando nessun evento arriva per un tempo insolitamente lungo. Su un sistema trafficato, il silenzio è un segnale.

I webhook sono la sua corsia preferenziale. La riconciliazione è la sua rete di sicurezza. Esegua entrambi.

Token ed edge case su Polygon

USDC e USDT. I pagamenti in stablecoin sono la ragione principale per cui gli sviluppatori configurano i webhook su Polygon, perché le commissioni sono basse e il regolamento è rapido. Si assicuri di sapere quale contratto usa ogni stablecoin su Polygon e metta nella whitelist quegli indirizzi, come descritto sopra.

POL nativo. I trasferimenti nativi non emettono log di token, quindi un listener basato solo sugli eventi Transfer li perderebbe. Confermi che il suo fornitore riporti anche i movimenti della moneta nativa se prevede di accettare POL.

Pagamenti da contratto a indirizzo. Un pagamento può provenire da un wallet smart contract o da un multisig, non da un account semplice. Non assuma che il mittente sia il cliente. Colleghi i pagamenti ai clienti tramite l’indirizzo di ricezione che ha generato per loro, non tramite il mittente.

Transazioni fallite e revertite. Una transazione revertita consuma gas ma non sposta nulla. Agisca solo sugli eventi che rappresentano trasferimenti andati a buon fine.

Dust e token spam. Token non richiesti compaiono regolarmente negli indirizzi. Ignori i contratti che non ha inserito nella whitelist.

Sviluppare in proprio o usare un’API unificata

Esistono tre percorsi realistici per le notifiche degli eventi su Polygon:

1. Eseguire un proprio nodo e listener. Massimo controllo, ma si fa carico di aggiornamenti del nodo, crescita dello storage, decodifica dei log, gestione delle riorganizzazioni e uptime. Sensato quando l’infrastruttura di catena è il suo prodotto.
2. Usare un nodo o un data provider generico e scrivere il filtraggio da sé. Minore onere operativo, ma deve comunque costruire sottoscrizioni, retry, decodifica e livello di firma.
3. Usare un’API focalizzata sui pagamenti che fornisce eventi decodificati e firmati. Scrive l’endpoint e la logica di business, nient’altro.

Per un team che vuole accettare o inviare crypto nel proprio prodotto, la terza via raggiunge solitamente la produzione più velocemente. Confrontiamo le opzioni più in dettaglio in Blockchain APIs compared: 6 types and when to use each.

La nostra prospettiva: i webhook sono un problema di registro, non di notifica

La maggior parte dei bug di integrazione che vediamo non riguardano la ricezione della richiesta HTTP. Riguardano ciò che accade dopo. I team trattano un webhook come un trigger (“pagamento arrivato, spedisci”) quando in realtà è solo un input per un registro che deve rimanere corretto sotto retry, riorganizzazioni e riavvii.

Questo influenza il modo in cui costruiamo Chaingateway. Forniamo eventi pre-decodificati, così il suo codice legge un importo e un token, non argomenti di log codificati in esadecimale. Firmiamo ogni richiesta con HMAC in modo che il suo endpoint possa respingere le falsificazioni. E copriamo Polygon accanto a Ethereum, Tron, Bitcoin, Solana, BNB Chain e Arbitrum attraverso un’unica API REST, così la logica del suo handler rimane la stessa quando aggiunge una seconda catena.

Il nostro consiglio: scriva prima il codice di idempotenza e riconciliazione, prima dell’happy path. Se può riprodurre lo stesso evento dieci volte e mescolare tre eventi e finire con il saldo corretto, il resto è facile. Il nostro articolo su l’elaborazione automatica dei depositi con i webhook illustra quel flusso end-to-end.

— Bitblade

Ottenere i webhook di Polygon con Chaingateway

Con i Webhook di Chaingateway può creare portafogli o registrare indirizzi tramite l’API, iscriversi agli eventi di pagamento e ricevere notifiche firmate presso il suo endpoint. La pagina API Polygon illustra l’invio e la ricezione di USDC e USDT su Polygon, mentre la Blockchain API copre portafogli, trasferimenti, dati di transazione decodificati e stima del gas sulle catene supportate.

I piani sono pubblicati nella pagina dei prezzi:

L’accesso a pagamento inizia dopo una prova gratuita, così può testare l’intero flusso, inclusi i controlli di firma e la gestione dei duplicati, prima di impegnarsi.

Una checklist per il lancio

Prima di indirizzare il traffico di produzione verso il suo endpoint, esegua questa verifica:

• Solo HTTPS, con un certificato valido.
• Firma verificata sul body grezzo, confronto a tempo costante.
• Vincolo di unicità sulla chiave dell’evento.
• Risposta 2xx entro un paio di secondi, lavoro spostato in coda.
• Indirizzi dei contratti in whitelist, importi e destinatari validati.
• Modello di stato con stati pending e finali, e una soglia di conferma documentata.
• Job di riconciliazione e un alert per eventi mancanti.
• Segreti memorizzati fuori dal repository e ruotabili senza downtime.
• Un test di replay: invii lo stesso evento più volte, e fuori ordine, in staging.

Fonti

• Riferimento Polygon Confirmation Time
• Tempo di conferma USDT per rete
• Documentazione per sviluppatori Polygon

Consigliati

• Blockchain Webhooks & Event Notifications
• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• The Use of Webhooks to Process Deposits Automatically