← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

Webhook per i depositi crypto: come funzionano

Come un webhook rileva un deposito crypto in entrata: webhook contro polling, campi del payload, verifica della firma HMAC e notifiche perse.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Un webhook è una richiesta HTTP che un servizio invia al tuo server quando accade un evento. Per i depositi crypto, l’evento è una transazione che corrisponde a un indirizzo che tieni sotto controllo. Chaingateway invia i dettagli della transazione al tuo endpoint, e il tuo codice accredita il cliente. Questo sostituisce il polling ripetuto di un’API blockchain alla ricerca di nuove transazioni.

Che cos’è un webhook?

Un webhook è un callback via HTTP. Fornisci al mittente un URL, e il mittente invia una richiesta POST a quell’URL quando si verifica un evento predefinito. Il corpo della richiesta è il payload. Pensa all’URL come a un numero di telefono che il mittente chiama ogni volta che succede qualcosa.

Webhook e API sono due modi di scambiare dati. Con un’API tu fai pull: il tuo codice chiede i dati a intervalli e verifica se è cambiato qualcosa. Con un webhook il provider fa push: ti contatta nel momento dell’evento. Il push fa risparmiare richieste e riduce il ritardo. Il pull conserva comunque un ruolo, perché un webhook ti dice solo che qualcosa è successo. Se ti servono il record completo o una verifica, chiedi all’API.

Webhook o polling: quale usare per i depositi?

Usa i webhook per sapere rapidamente di un deposito, e l’API per verificarlo e riconciliarlo. I due funzionano bene insieme.

ApproccioPunto di forzaPunto debole
Polling dell’APIControlli i tempi e puoi riprendere dopo un’interruzioneSpreca richieste, e il ritardo è pari al tuo intervallo
WebhookNotifica poco dopo che la transazione è stata rilevataUna notifica può andare persa se il tuo endpoint è giù

Su Chaingateway i webhook sono disponibili per Bitcoin, Ethereum, BNB Smart Chain, Tron, Polygon e Arbitrum. Solana non ha webhook, quindi lì interroghi le transazioni.

Come imposto un webhook per i depositi?

Crea un endpoint ricevente, poi registra un webhook per l’indirizzo che vuoi monitorare. L’endpoint deve essere raggiungibile da internet pubblico. Non devi autorizzare gli indirizzi IP di Chaingateway, perché il servizio chiama il tuo URL pubblico come qualsiasi altro client.

Un webhook richiede un url e almeno uno tra from o to. I filtri facoltativi sono contractaddress, token_id e type, che su Ethereum è ETH, ERC20 o ERC721. Puoi anche impostare un reference fino a 255 caratteri, ad esempio il numero del tuo ordine. Questa richiesta monitora i depositi di un token ERC-20 (qui il contratto USDT) verso un indirizzo.

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

Una chiamata riuscita restituisce lo stato 201 e l’ID del webhook in data.webhook. Crea il webhook prima che il cliente paghi, così il pagamento non può avvenire prima che il monitoraggio esista.

Che cosa contiene la notifica?

Ogni POST contiene i campi che ti servono per associare il pagamento a un ordine. Questo esempio è tratto dalla documentazione di Chaingateway per un trasferimento TRC20.

{
"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
}

Il txid identifica la transazione, e webhook_id ti dice quale monitoraggio è scattato. Salva il txid con un indice univoco. Se la stessa notifica arriva due volte, il secondo inserimento fallisce e tu la salti.

Come verifico che una notifica sia autentica?

Controlla l’header X-Signature prima di fidarti del payload. Chaingateway calcola un HMAC con SHA-256 sul txid, usando il tuo segreto personale come chiave, e invia il risultato codificato in Base64. L’HMAC è definito nella RFC 2104. Il tuo server ripete il calcolo e confronta i due valori con un confronto a tempo costante.

Imposti il segreto personale nelle impostazioni del profilo. Una volta che esiste un segreto, l’header viene aggiunto a tutti i webhook in uscita. La documentazione sulla firma contiene il codice di verifica per Python, Java, PHP e JavaScript.

Come si presenta un ricevitore minimo?

Un ricevitore verifica la firma, registra l’evento una sola volta e risponde rapidamente. Questo esempio con Express tiene in memoria gli ID delle transazioni già viste, per restare breve. In produzione usa una tabella di database con un indice univoco su txid.

const crypto = require('crypto');
const express = require('express');
const app = express();
const seen = new Set();
app.post('/hooks/deposits', express.json(), (req, res) => {
const { txid, to, amount } = req.body;
const expected = crypto
.createHmac('sha256', process.env.PERSONAL_SECRET)
.update(txid)
.digest('base64');
const received = req.get('X-Signature') || '';
const valid =
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!valid) return res.sendStatus(401);
if (!seen.has(txid)) {
seen.add(txid);
// credit the order that belongs to the address `to` for `amount`
}
res.sendStatus(200);
});
app.listen(3000);

Prova prima il ricevitore su una testnet. Invia l’header X-Network: testnet quando crei il webhook, poi invia un piccolo trasferimento di prova all’indirizzo monitorato. La notifica dovrebbe arrivare con il txid di quel trasferimento. La documentazione consiglia di creare il webhook subito prima che venga effettuato il pagamento, quindi crealo nel momento in cui consegni l’indirizzo.

Che cosa succede se il mio server è giù?

La notifica non viene inviata di nuovo in automatico. Se il tuo endpoint non accetta una notifica, questa compare nell’elenco delle notifiche fallite su GET /api/v2/{chain}/webhooks/notifications/failed. Per ogni voce avvii una nuova consegna con POST /api/v2/{chain}/webhooks/notifications/{id}/retry. Se anche il nuovo tentativo fallisce, la voce torna nell’elenco.

Restituisci un codice di successo appena hai salvato l’evento, e svolgi il lavoro lento dopo. La RFC 9110 definisce la classe 2xx dei codici di stato come indicazione che la richiesta è stata ricevuta e accettata. Controlla regolarmente l’elenco dei falliti e riconcilia i tuoi record con l’API, così una lacuna non passa inosservata. La guida alla consegna dei webhook tratta duplicati e ordine in modo più dettagliato.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API 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.