← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

Webhook Polygon: eventi on-chain in tempo reale

Come funzionano i webhook Polygon, cosa controllare su PoS (riorganizzazioni, conferme, duplicati) e come costruire un gestore sicuro per depositi USDC e POL.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Percorso geometrico di un evento dal registro al webhook

Un webhook Polygon è una callback HTTP che un servizio invia al Suo server quando accade un evento sulla catena, ad esempio un deposito USDC su un Suo indirizzo. Il provider osserva la catena e invia un POST firmato, invece di fare polling su un nodo RPC. Questa guida copre il gestore e i casi limite di Polygon.

TL;DR

  • Un webhook sostituisce il polling: il provider osserva Polygon e invia gli eventi (depositi, trasferimenti, movimenti di token) al Suo endpoint.
  • Polygon finalizza le transazioni in pochi secondi, ma serve comunque una policy di conferma prima di accreditare i fondi.
  • Consideri ogni consegna come potenzialmente duplicata, in ritardo o fuori ordine: verifichi la firma, salvi l’ID dell’evento ed elabori in modo idempotente.
  • Confermi rapidamente la ricezione, esegua il lavoro in una coda e riconcili con la catena secondo una pianificazione. Chaingateway non ritenta automaticamente le notifiche fallite.
  • Chaingateway Webhooks consegnano eventi Polygon firmati con HMAC, con mittente, destinatario, contratto del token e importo già decodificati, così Lei evita di gestire nodi e di analizzare i log.

Che cos’è un webhook Polygon?

Polygon PoS è una catena EVM. Ogni trasferimento ERC-20, che si tratti di USDC, USDT o di un token emesso da Lei, emette un log Transfer. Il POL nativo si muove come trasferimento di valore, non come log Transfer ERC-20. L’RPC grezzo fornisce entrambi in forme diverse: log per i token, dati di transazione per la moneta nativa. Se vuole sapere che un cliente ha pagato, deve ricomporre da sé il quadro.

Un servizio di webhook fa questa ricomposizione. Lei si iscrive a un indirizzo (o a un insieme di indirizzi), e quando accade un evento corrispondente il servizio invia un payload JSON al Suo URL. Un payload utile indica l’hash della transazione, il mittente, il destinatario, il contratto del token, l’importo, il numero di blocco e un identificativo univoco dell’evento. È 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: avvisami quando i fondi arrivano a questi indirizzi. È ciò che serve ai flussi di pagamento.
  • Webhook per eventi di contratto: avvisami 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 sulle proprie operazioni. Appartengono alla documentazione di quel prodotto, non a un listener generico della catena.

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

Perché i webhook battono il polling su Polygon?

Se interroga un endpoint RPC per i nuovi blocchi e filtra i log da sé, affronta un compromesso senza una buona soluzione:

  • Interroga ogni pochi secondi e consuma i limiti di frequenza, pagando risposte per lo più vuote.
  • Interroga ogni minuto e il cliente fissa uno spinner per un minuto dopo aver pagato.
  • Perde un intervallo dopo un riavvio e nel registro compare una lacuna silenziosa.

I webhook ribaltano la situazione. Il provider si occupa dell’osservazione e della contabilità dei blocchi. Il Suo compito si riduce a gestire un endpoint che tratti correttamente gli eventi. Approfondiamo i compromessi architetturali nel nostro articolo su webhook e WebSocket, incluso lo schema ingest, coda e fan-out che raccomandiamo.

Quante conferme servono su Polygon?

Attenda la finalità, che Polygon raggiunge in pochi secondi. Un webhook che scatta alla prima rilevazione di una transazione è veloce, ma non è definitivo. Prima di consegnare merce o accreditare un saldo, decida che cosa attendere.

La documentazione sulla finalità di Polygon afferma che la finalità deterministica si raggiunge in 2-5 secondi dall’aggiornamento Heimdall v2. Le milestone forniscono questa finalità senza attendere un checkpoint su Ethereum. Un blocco finalizzato è irreversibile, quindi dopo quel punto non esiste rischio di riorganizzazione. Può interrogare l’ultimo blocco finalizzato con il metodo standard eth_getBlockByNumber e il tag di blocco "finalized".

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

Importo del pagamentoGestione suggeritaMotivo
Piccolo (beni digitali, mance)Accredito al primo evento, segnato come “in sospeso”UX rapida, perdita bassa se si verifica una rara riorganizzazione
Medio (abbonamenti, ricariche)Accredito dopo una profondità di blocchi moderataEquilibrato
Grande (fatture, prelievi)Accredito solo quando il blocco è finalizzatoIl rischio di riorganizzazione conta più della velocità

Questa tabella è la nostra policy suggerita, non una regola di Polygon. Scelga numeri che corrispondano alla Sua tolleranza al rischio e li documenti.

Nel Suo modello dati, assegni a ogni pagamento in entrata uno stato come detected, confirming e final. Mostri subito al cliente il primo stato e sposti i fondi solo sull’ultimo. Salvi il numero di blocco del primo evento. A intervalli, lo confronti con il numero dell’ultimo blocco finalizzato, e porti il pagamento a final quando il blocco finalizzato lo ha superato.

Come è fatto un gestore webhook sicuro su Polygon?

La documentazione per sviluppatori di Polygon include una guida alla ricezione dei webhook per uno dei prodotti di Polygon. I suoi principi valgono per ogni integrazione di webhook: verificare la consegna, e applicarla senza doppia elaborazione né stato obsoleto. La OWASP Webhook Security Cheat Sheet elenca gli stessi punti. Ecco la stessa disciplina applicata agli eventi di catena.

1. Verifichi la firma prima di tutto

Chiunque trovi il Suo URL può inviarvi un POST. Senza verifica, un malintenzionato 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 i webhook con HMAC-SHA256. L’header X-Signature contiene l’HMAC codificato in Base64 dell’ID della transazione (txid) del payload, calcolato con il Suo segreto personale come chiave. Lo ricalcoli e confronti i due valori con un confronto a tempo costante. La documentazione sulla firma contiene codice per diversi linguaggi, e il nostro articolo su una nuova funzione per rafforzare la sicurezza dei webhook spiega la configurazione.

2. Renda l’elaborazione idempotente

Consideri che una notifica possa arrivare più di una volta, ad esempio quando reinvia una notifica fallita. Salvi una chiave univoca per evento, idealmente l’hash della transazione o l’ID dell’evento fornito dal provider. Applichi un vincolo di unicità nel database:

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

Se l’inserimento non modifica alcuna riga, quell’evento l’ha già visto. Restituisca 200 e si fermi. Esegua l’inserimento e l’aggiornamento del saldo nella stessa transazione di database, così un crash non può lasciare l’uno senza l’altro.

3. Confermi rapidamente, elabori dopo

Restituisca un 2xx non appena l’evento è verificato e salvato in sicurezza. Svolga il lavoro lento, come inviare un’email al cliente, aggiornare i registri e chiamare altri servizi, da una coda. Se il gestore è lento, il mittente può andare in timeout, e Lei si ritroverà a fare debug di notifiche fallite.

4. Non dia per scontato l’ordine

Due eventi sullo stesso pagamento possono arrivare in qualsiasi ordine, ad esempio un aggiornamento di conferma prima della rilevazione originale. Confronti i numeri di blocco o i campi di sequenza e ignori qualsiasi cosa più vecchia dello stato che già possiede. Non permetta mai a un evento “detected” in ritardo di sovrascrivere un record “final”.

5. Convalidi 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. Su Polygon questo conta più di quanto molti si aspettino, perché chiunque può pubblicare un token chiamato “USDC” e inviarlo al Suo indirizzo. Confronti gli indirizzi dei contratti, mai i simboli.

6. Pianifichi i guasti

Il Suo server sarà giù prima o poi. Decida in anticipo come recuperare:

  • Controlli l’elenco delle notifiche fallite. Chaingateway non le ritenta automaticamente. Le elenca su GET /api/v2/polygon/webhooks/notifications/failed, e Lei reinvia ciascuna con POST /api/v2/polygon/webhooks/notifications/{id}/retry.
  • Esegua un job di riconciliazione, ad esempio ogni pochi minuti, che controlli saldi o trasferimenti recenti dei Suoi indirizzi e segnali tutto ciò che il Suo registro dei webhook non ha visto.
  • Imposti un avviso quando non arrivano eventi per un tempo insolitamente lungo. Su un sistema molto attivo, il silenzio è un segnale.

I webhook sono la Sua via rapida. La riconciliazione è la Sua rete di sicurezza. Li faccia girare entrambi.

Quali token e casi limite contano su Polygon?

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

POL nativo. Il POL è il token nativo di Polygon Chain, secondo la documentazione Polygon. I trasferimenti nativi non sono eventi Transfer ERC-20, quindi un listener costruito solo su quegli eventi li perderà. Nell’API dei webhook Polygon di Chaingateway, il filtro type accetta MATIC, ERC20 e ERC721. Il valore MATIC indica il tipo di moneta nativa, quindi lo verifichi prima di basarvi i pagamenti in POL.

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

Transazioni fallite e annullate. Una transazione annullata consuma gas ma non sposta nulla. Agisca solo sugli eventi che rappresentano trasferimenti riusciti.

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

Lista di cose da fare ed evitare per i token Polygon: inserire in whitelist i contratti delle stablecoin, confermare che il POL nativo viene segnalato, collegare i clienti tramite indirizzo ricevente e agire solo sui trasferimenti riusciti; non dare per scontato che il mittente sia il cliente, ascoltare solo gli eventi dei token, accettare contratti non in elenco o agire su transazioni annullate

Conviene costruirlo da sé o usare un’API unificata?

Ci sono tre percorsi realistici per le notifiche di eventi Polygon:

  1. Far girare un nodo e un listener propri. Controllo massimo, ma Lei gestisce gli aggiornamenti del nodo, la crescita dello storage, la decodifica dei log, la gestione delle riorganizzazioni e l’uptime. Ha senso quando l’infrastruttura blockchain è il Suo prodotto.
  2. Usare un provider generico di nodi o di dati e scrivere da sé il filtraggio. Meno onere operativo, ma Lei costruisce comunque sottoscrizioni, tentativi, decodifica e lo strato di firma.
  3. Usare un’API orientata ai pagamenti che consegna eventi decodificati e firmati. Lei scrive solo l’endpoint e la logica di business.

Per un team che vuole accettare o inviare crypto nel proprio prodotto, il terzo percorso di solito arriva in produzione più in fretta. Confrontiamo le opzioni più in dettaglio in API blockchain a confronto: 6 tipi e quando usarli.

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

La maggior parte dei problemi di integrazione che vediamo non riguarda la ricezione della richiesta HTTP. Riguarda ciò che accade dopo. I team trattano un webhook come un innesco (“pagamento arrivato, spedisci”), mentre in realtà è un input per un registro che deve restare corretto in presenza di tentativi ripetuti, riorganizzazioni e riavvii.

Tre schede intitolate Registro, Test di replay e HMAC: tentativi, riorganizzazioni e riavvii minacciano la correttezza; riprodurre un evento dieci volte e mescolarne tre; firmare ogni richiesta per respingere le falsificazioni

Questo influenza il modo in cui costruiamo Chaingateway. Consegniamo eventi decodificati, così il Suo codice legge un importo e un contratto di token, non topic di log codificati in esadecimale. Firmiamo ogni webhook con HMAC, così il Suo endpoint può respingere le falsificazioni. E copriamo Polygon insieme a Ethereum, Tron, Bitcoin, Solana, BNB Chain e Arbitrum tramite un’unica API REST, così la logica del gestore resta la stessa quando aggiunge una seconda catena.

Il nostro consiglio: scriva prima il codice di idempotenza e di riconciliazione, prima del percorso felice. Se può riprodurre lo stesso evento dieci volte e mescolarne tre, e ottenere comunque il saldo corretto, il resto è semplice. Il nostro articolo su come elaborare automaticamente i depositi con i webhook illustra questo flusso dall’inizio alla fine.

— Bitblade

Come ottengo webhook Polygon con Chaingateway?

Con i Chaingateway Webhooks crea wallet o registra indirizzi tramite l’API, si iscrive agli eventi di pagamento e riceve notifiche firmate sul Suo endpoint. La pagina Polygon API descrive l’invio e la ricezione di USDC e USDT su Polygon, e la Blockchain API copre wallet, trasferimenti, transazioni decodificate e prezzi del gas sulle catene supportate.

Crei un webhook con POST /api/v2/polygon/webhooks. Richiede un url e almeno uno tra from o to. Può filtrare per type e contractaddress, e impostare un reference fino a 255 caratteri, ad esempio il numero del Suo ordine. Aggiunga l’header X-Network: testnet per provare sulla rete di test.

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

L’indirizzo del contratto in questo esempio è il contratto USDC nativo su Polygon PoS, come riportato nella documentazione sugli indirizzi dei contratti di Circle.

I piani sono pubblicati nella pagina dei prezzi:

PianoMensileAnnuale
Plus49 € al mese490 € all’anno
Pro99 € al mese990 € all’anno
Premium249 € al mese2.490 € all’anno
Enterprise499 € al mese4.990 € all’anno

L’accesso a pagamento parte dopo una prova gratuita, quindi 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 al Suo endpoint, verifichi questi punti:

  • Solo HTTPS, con un certificato valido.
  • X-Signature verificata rispetto al txid, con un confronto a tempo costante.
  • Vincolo di unicità sulla chiave dell’evento.
  • 2xx restituito entro un paio di secondi, con il lavoro spostato in una coda.
  • Indirizzi dei contratti consentiti da un elenco, importi e destinatari convalidati.
  • Modello di stato con stati in sospeso e finali, e una soglia di conferma documentata.
  • Job di riconciliazione e avviso per gli eventi mancanti.
  • Segreti conservati fuori dal repository e ruotabili senza downtime.
  • Un test di replay: in staging, invii più volte lo stesso evento, anche fuori ordine.

Fonti

Consigliati

Domande frequenti

Dipende dal provider. I trasferimenti di token emettono log facili da tracciare, mentre i trasferimenti nativi richiedono un monitoraggio a livello di transazione. Nell’API dei webhook Polygon di Chaingateway, il filtro type accetta MATIC, ERC20 e ERC721, quindi verifichi il tipo di moneta nativa con un piccolo trasferimento prima di basarvi i pagamenti in POL.

Non esiste una regola unica, ma Polygon finalizza rapidamente. La documentazione sulla finalità di Polygon afferma che le milestone finalizzano in genere una transazione in 2-5 secondi, e il tag di blocco finalized restituisce l’ultimo blocco irreversibile. I pagamenti piccoli vengono spesso accreditati prima, come “in sospeso”. Commisuri la soglia all’importo a rischio.

La notifica non viene inviata di nuovo in automatico. Chaingateway elenca le notifiche fallite, e Lei reinvia ciascuna tramite l’endpoint di retry. Esegua anche un job di riconciliazione proprio, che confronti i Suoi registri con la catena, così le lacune non restano inosservate.

Consideri che possa accadere, ad esempio quando reinvia una notifica fallita. Salvi una chiave evento univoca con un vincolo nel database, e restituisca 200 per gli eventi già elaborati.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta API Polygon per il riferimento completo degli endpoint.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.