Webhook per pagamenti crypto: come funzionano e costruirli

Un webhook per pagamenti crypto è una richiesta HTTP che un servizio blockchain invia al Suo server quando accade qualcosa on-chain, per esempio l’arrivo di un deposito all’indirizzo di un cliente. Invece di chiedere alla rete ogni pochi secondi se un pagamento è arrivato, Lei fornisce al provider un URL, e sarà il provider a chiamarla.

Per farlo girare in produzione servono quattro elementi: un endpoint pubblico, la verifica della firma, la gestione idempotente dei duplicati e un piano di riserva per le consegne mancate. Questa guida li tratta uno per uno.

TL;DR

• Un webhook invia un evento al Suo server quando avviene un pagamento o un evento del wallet, così evita il polling costante e il carico che genera.
• Verifichi la firma di ogni richiesta prima di fidarsi di un qualsiasi campo. Con Chaingateway la firma copre solo l’ID della transazione, quindi verifichi Lei importo e destinatario.
• Risponda con un 2xx in fretta, e svolga il lavoro vero in un job in background.
• Consideri ogni evento come possibilmente ripetuto: memorizzi gli ID degli eventi e renda idempotenti gli aggiornamenti degli ordini.
• Mantenga un job di riconciliazione lento per i pagamenti in sospeso. Chaingateway non ritenta da sola le notifiche fallite, quindi una consegna mancata lascerebbe un ordine bloccato.

Che cosa sono i webhook per pagamenti crypto?

Un webhook è una callback. Registri un URL e indichi al provider quali eventi Le interessano. Quando uno di questi si verifica, il provider invia una richiesta POST con un corpo JSON che lo descrive. Per i pagamenti crypto, questi eventi sono di solito un trasferimento in arrivo verso un indirizzo monitorato, un trasferimento in uscita oppure un trasferimento di token su un contratto.

L’alternativa è il polling. Il Suo server chiama un’API a intervalli regolari e confronta il risultato con quello precedente. Il polling è semplice da scrivere e dispendioso da far girare. Ogni richiesta che non restituisce nulla di nuovo costa limiti di frequenza, calcolo e latenza, e il ritardo tra un pagamento e la Sua reazione è lungo quanto il Suo intervallo. Con più catene e migliaia di indirizzi di clienti, il numero di chiamate si moltiplica in fretta.

I webhook invertono la direzione. Il provider controlla la catena, abbina le transazioni agli indirizzi che Lei ha sottoscritto e La notifica una sola volta. Il tempo di reazione scende a pochi secondi, e la Sua infrastruttura resta inattiva finché non c’è qualcosa da fare. Un’argomentazione più lunga sui depositi è nel nostro articolo su come i webhook elaborano i depositi automaticamente.

Webhook contro polling in sintesi

L’ultima riga è la risposta pratica. I webhook devono essere il segnale principale, e il polling una rete di sicurezza lenta che controlla solo i pagamenti ancora in sospeso. Lo esegua solo per le fatture ancora in attesa, così una consegna mancata viene trovata in pochi minuti e il numero di richieste resta basso.

Come rileva un webhook un pagamento crypto?

La parte del provider non la vede, ma capirla spiega gran parte del comportamento che incontrerà in fase di test.

1. Sottoscrizione. Crei un wallet o registri un indirizzo, poi registri per esso un webhook tramite l’API del provider. La sottoscrizione contiene il Suo URL di callback e i filtri, come mittente, destinatario, indirizzo del contratto e tipo di transazione.
2. Monitoraggio. Il provider gestisce nodi per ogni catena supportata e legge ogni nuovo blocco. Ogni transazione viene confrontata con le sottoscrizioni e, per i token, con i log dei trasferimenti del contratto.
3. Decodifica. I dati grezzi della catena non sono leggibili. Un trasferimento di token su Ethereum è una voce di log codificata, e Bitcoin ha input e output invece di un mittente e un destinatario. Il provider trasforma tutto in un payload leggibile.
4. Consegna. Il provider invia il payload al Suo URL. Se il Suo server non risponde con un codice di successo, ciò che accade dopo dipende dal provider. Alcuni ritentano secondo una pianificazione. Chaingateway non ritenta da sola: elenca le notifiche fallite, e Lei chiede che ciascuna venga inviata di nuovo.

Una notifica Chaingateway contiene i campi id, webhook_id, from, to, blocknumber, datetime, type, contractaddress, tokenid, txid e amount. Gli stessi nomi di campo valgono su Ethereum, BNB Smart Chain, Polygon, Arbitrum e Tron. I webhook Bitcoin filtrano solo per mittente e destinatario. Solana non ha webhook. Sono supportati standard di token come ERC-20, BEP-20 e TRC-20, il che conta, perché la maggior parte dei pagamenti reali sono trasferimenti di stablecoin e non della moneta nativa.

Quali eventi conviene sottoscrivere

Parta in modo ristretto. In Chaingateway un webhook è definito dai filtri, quindi ogni tipo di evento corrisponde a una combinazione di filtri:

• Un trasferimento in arrivo a un indirizzo di deposito del cliente usa to. È l’evento centrale per accreditare un conto o segnare una fattura come pagata.
• Un trasferimento in uscita usa from, per esempio per vedere quando un pagamento o uno svuotamento arriva sulla catena.
• Un trasferimento di token usa type (come ERC20 o TRC20) con un contractaddress.
• Un trasferimento NFT usa il campo token_id con un tipo ERC721 o TRC721.
• Il campo facoltativo reference, fino a 255 caratteri, permette di legare un webhook a un ordine o a un cliente nel Suo sistema.

Una notifica annuncia che è stata vista una transazione corrispondente al filtro. Se la considera definitiva è una Sua politica, come spiega la sezione sulla profondità di conferma.

Il nostro articolo sui webhook Polygon senza polling mostra come appare tutto questo su una singola catena.

Come si configura ed elabora un endpoint webhook?

L’endpoint è una normale route HTTPS sul Suo server. La differenza tra una demo e un gestore di produzione sta in poche abitudini.

Requisiti dell’endpoint

L’URL deve essere raggiungibile da internet pubblico tramite HTTPS. Gli indirizzi localhost e le reti private non possono ricevere chiamate, quindi durante lo sviluppo Le serve un tunnel che esponga la Sua porta locale. Tenga la route dedicata ai webhook, accetti solo POST, e non la metta dietro schermate di login o middleware CSRF che respingerebbero una richiesta proveniente da una macchina.

Il gestore deve rispondere in fretta. L’indicazione comune, per esempio nella documentazione dei webhook di Stripe, è restituire rapidamente un codice di successo, prima di qualsiasi logica complessa che possa andare in timeout. Successo significa uno stato 2xx come definito nella RFC 9110. La stessa regola vale per gli eventi crypto. Se aggiorna un database, invia un’email e chiama un sistema contabile prima di rispondere, un servizio a valle lento può far considerare il recapito fallito al provider.

Uno schema affidabile è questo:

1. Legga il corpo della richiesta.
2. Verifichi la firma.
3. Scriva l’evento in una coda o in una tabella eventi con il suo ID.
4. Restituisca 200.
5. Lasci che un worker elabori l’evento in coda.

Come si verificano le firme dei webhook?

Chiunque trovi quell’URL può inviarLe JSON. Se il gestore accredita un conto perché una richiesta dice che un deposito è arrivato, una richiesta falsa è un furto. La verifica della firma chiude questa porta.

Lo schema tipico è HMAC, definito nella RFC 2104. Il provider calcola un hash con chiave usando un segreto che solo Lei e lui conoscete, e invia il risultato in un header. Lei ricalcola l’hash e confronta. Tre dettagli fanno inciampare molti:

• Sappia cosa viene firmato. Molti provider firmano l’intero corpo della richiesta, il che significa che deve verificare sui byte originali, non su JSON riserializzato. Chaingateway firma solo l’ID della transazione.
• Confronti in tempo costante. Usi la funzione di confronto sicuro del Suo linguaggio invece di un semplice controllo di uguaglianza.
• Controlli un timestamp quando lo schema ne fornisce uno. Rifiutare i timestamp vecchi limita il replay di una richiesta catturata. Lo schema di Chaingateway non ha timestamp, quindi deduplichi sull’ID della transazione.

Chaingateway invia la firma nell’header X-Signature una volta impostato un segreto personale nel Suo profilo. Il valore è l’HMAC-SHA256, codificato in Base64, del campo txid, con quel segreto come chiave. La guida alla verifica della firma contiene un gestore Node.js funzionante, e la documentazione ha le versioni in Python, Java e PHP. Poiché viene firmato solo il txid, una firma valida non dimostra che amount o to siano invariati. Li verifichi con la fattura, o con la catena, prima di accreditare qualsiasi cosa.

Conservi il segreto in una variabile d’ambiente o in un gestore di segreti, mai nel repository, e lo rigeneri se mai compare in un log. Un segreto rigenerato ha effetto immediato.

Come si gestiscono ritentativi, duplicati e conferme lente?

Le reti falliscono e i deploy riavviano i server. Il Suo gestore vedrà prima o poi lo stesso evento due volte, per esempio dopo un reinvio, e a volte eventi fuori ordine. Lo progetti fin dall’inizio per questo.

Renda l’elaborazione idempotente

Ogni evento porta qualcosa che lo identifica. In una notifica Chaingateway è il txid, insieme al webhook_id. Salvi questo identificatore con un vincolo di unicità prima di agire. Se l’inserimento fallisce perché la chiave esiste già, ha già visto l’evento e può restituire 200 senza fare nulla.

Poi renda sicura da ripetere l’azione di business stessa. «Imposta la fattura 1042 come pagata con la transazione X» è idempotente. «Aggiungi 50 al saldo» non lo è. Preferisca la prima forma, oppure colleghi la variazione di saldo al record dell’evento unico in un’unica transazione di database.

Rispetti la profondità di conferma

Una transazione che compare in un blocco non equivale a un pagamento su cui spedire la merce. Le catene differiscono nella rapidità con cui un blocco diventa improbabile da riorganizzare, e la soglia giusta dipende dall’importo e dall’asset. Definisca una politica per catena e per dimensione dell’ordine, e memorizzi lo stato di ogni pagamento: rilevato, in conferma, confermato, fallito. Il webhook che annuncia il rilevamento dovrebbe spostare un ordine su «pagamento visto», non su «evaso».

Sottopagamenti, sovrapagamenti e token sbagliati

I clienti inviano l’importo sbagliato più spesso di quanto chiunque si aspetti. Il gestore dovrebbe confrontare importo ricevuto e asset con la fattura e ramificare: corrispondenza esatta, importo inferiore, superiore o un token inatteso. Decida in anticipo se accredita automaticamente la differenza, se la trattiene per verifica o se rimborsa. Un payload decodificato con asset e importo come campi separati rende questo confronto poche righe di codice, invece di un esercizio di parsing.

Tenga una rete di sicurezza

Una consegna può fallire, e Chaingateway non la ritenta. Le notifiche fallite compaiono in GET /api/v2/<chain>/webhooks/notifications/failed, e ciascuna può essere reinviata con POST /api/v2/<chain>/webhooks/notifications/{id}/retry. Attivi un job pianificato, ogni pochi minuti, che controlli quell’elenco e guardi le fatture ancora in sospeso oltre un tempo ragionevole. Quando trova un pagamento che il webhook non ha mai segnalato, lo fa passare per lo stesso percorso di elaborazione. Un solo percorso di codice per entrambe le fonti significa un solo insieme di bug.

Come si testa e si monitora un endpoint webhook?

Costruisca la fiducia a strati:

1. Test locale. Scriva un piccolo script che firmi un payload di esempio con il suo segreto di test e lo invia al Suo endpoint. Verifichi che una firma valida passi e che un txid modificato fallisca.
2. Prova sulla testnet. Crei un wallet sulla rete di test con l’header X-Network: testnet, registri un webhook e invii un piccolo trasferimento da un faucet. Vedrà la sequenza reale degli eventi, incluso il ritardo prima della notifica, che nessun payload di esempio insegna.
3. Prova dei duplicati. Invii lo stesso evento valido cinque volte. La Sua fattura dovrebbe cambiare una sola volta, e i log dovrebbero mostrare quattro duplicati saltati.
4. Prova di guasto. Faccia restituire deliberatamente 500 al gestore. Poi trovi la notifica nell’elenco dei falliti, ripristini il gestore e la reinvii. Dovrebbe essere elaborata una sola volta.

Una volta in produzione, registri ogni ID di evento in ingresso, l’esito della verifica, l’esito dell’elaborazione e il tempo impiegato. Imposti alert su tre cose: fallimenti di firma (un segreto configurato male o un aggressore), una coda che cresce (worker in ritardo) e fatture in sospeso molto più a lungo del normale (problemi silenziosi di consegna).

Problemi comuni e cause più frequenti:

Come si iniziano a ricevere eventi di pagamento con Chaingateway?

Crei un webhook con una sola richiesta a POST /api/v2/<chain>/webhooks. L’esempio registra un osservatore di depositi TRC20 con un riferimento al Suo ordine:

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "TWrTTVizHkF3LxTiWE9vCnhWC7CBpNXe22",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "type": "TRC20",
    "url": "https://shop.example.com/hooks/crypto",
    "reference": "order-10442"
  }'

I Chaingateway Webhooks lavorano insieme alla Blockchain API, quindi l’evento che segnala l’arrivo di un deposito e la chiamata che lo inoltra vivono sotto un unico account.

I piani sono pubblicati nella pagina dei prezzi: Plus costa 49 € al mese, Pro 99 €, Premium 249 € ed Enterprise 499 €, oppure 490 €, 990 €, 2.490 € e 4.990 € all’anno con fatturazione annuale. La prova gratuita di 7 giorni non richiede carta né KYC, quindi può collegare il Suo endpoint ed eseguire prima le prove descritte sopra.

Fonti

• Webhooks, documentazione Stripe
• HMAC: hashing con chiave per l’autenticazione dei messaggi, RFC 2104
• Codici di successo 2xx, HTTP Semantics, RFC 9110

Consigliati

• Il ruolo dei webhook nell’elaborazione automatica dei depositi
• Webhook contro WebSocket per sviluppatori: schema ingest, coda e fan-out
• Webhook Polygon: eventi on-chain in tempo reale senza polling
• Avvisi crypto in tempo reale: app di prezzo contro avvisi webhook