Verifica della firma dei webhook con segreto personale
Imposti un segreto personale e Chaingateway firma ogni webhook con l'header X-Signature. Come funziona l'HMAC, un controllo in Node.js e cosa non copre.
Verificato da Maurice Sobiera
Un segreto personale è una chiave che imposti nel tuo profilo Chaingateway. Una volta creato, ogni webhook in uscita porta un header X-Signature: un HMAC-SHA256 dell’ID della transazione, firmato con quel segreto e codificato in Base64. Il tuo server ricalcola il valore e lo confronta, il che dimostra che la richiesta arriva da Chaingateway.
Perché i webhook hanno bisogno di una firma?
Un endpoint webhook è un URL pubblico, e chiunque lo conosca può inviargli una richiesta. Senza un controllo, una falsa richiesta «pagamento ricevuto» potrebbe sbloccare merce o accreditare un conto. Un segreto condiviso risolve il problema. Solo Chaingateway e il tuo server conoscono la chiave, quindi solo loro possono produrre una firma corrispondente. La costruzione è HMAC, definita nella RFC 2104: una funzione di hash combinata con una chiave segreta.
Come si imposta un segreto personale?
Apri le impostazioni del profilo nella dashboard, trova la scheda del segreto personale per i webhook e clicca su «Set Personal Secret». Per sostituire un segreto esistente, clicca su «Regenerate Secret». Due dettagli dalla documentazione contano:
- Impostare un segreto per la prima volta attiva l’header
X-Signaturesu tutti i webhook in uscita. Assicurati che il tuo server accetti il nuovo header e lo verifichi prima di farvi affidamento. - Un segreto rigenerato ha effetto immediato. Aggiorna il gestore prima di cliccare, oppure nello stesso momento, altrimenti le notifiche valide non superano la verifica.
Come si costruisce la firma?
La procedura documentata ha tre passaggi. Leggi il campo txid dal payload del webhook. Calcola HMAC-SHA256 con il tuo segreto personale come chiave e la stringa txid come messaggio. Codifica il risultato in Base64 e confrontalo con l’header. Un payload appare così (dalla guida ai webhook):
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}Come si verifica la firma sul server?
Ricalcola l’HMAC dal txid e confrontalo con l’header in tempo costante. Il seguente gestore Express lo fa. Legge il segreto da una variabile d’ambiente, rifiuta un header mancante o di dimensione errata, e risponde con 200 solo alle richieste valide:
const crypto = require('crypto');const express = require('express');
const app = express();app.use(express.json());
function isValid(txid, received, secret) { const expected = crypto.createHmac('sha256', secret).update(txid).digest('base64'); const a = Buffer.from(expected); const b = Buffer.from(received || ''); // timingSafeEqual throws when lengths differ, so check first return a.length === b.length && crypto.timingSafeEqual(a, b);}
app.post('/hooks/deposit', (req, res) => { const ok = isValid(req.body.txid, req.get('X-Signature'), process.env.CG_PERSONAL_SECRET); if (!ok) return res.sendStatus(401); // process req.body.txid, deduplicate on it, then acknowledge res.sendStatus(200);});
app.listen(3000);La documentazione ha anche versioni in Python, Java e PHP. In Python, usa hmac.compare_digest per il confronto. In Node.js, crypto.timingSafeEqual fa lo stesso lavoro. Un semplice confronto con == può far trapelare informazioni sui tempi.
Come si testa il gestore?
Calcola una firma da solo e invia al tuo server locale una notifica falsa. Il comando openssl qui sotto produce lo stesso HMAC in Base64 che il gestore si aspetta. Usa un segreto di test, mai quello reale:
TXID=18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988SIG=$(printf '%s' "$TXID" | openssl dgst -sha256 -hmac "test-secret" -binary | base64)
curl -i -X POST http://localhost:3000/hooks/deposit \ -H "Content-Type: application/json" \ -H "X-Signature: $SIG" \ -d "{\"txid\": \"$TXID\"}"Avvia il server con CG_PERSONAL_SECRET=test-secret. La richiesta restituisce 200. Cambia un solo carattere del segreto o della firma, e restituisce 401. Ripeti questo test dopo ogni deploy del gestore, e di nuovo dopo aver rigenerato il segreto reale.
Che cosa non copre la firma?
Copre l’ID della transazione e nient’altro. Secondo la costruzione documentata, solo txid entra nell’HMAC. Ne derivano due conseguenze:
- Una firma valida dimostra che Chaingateway ha inviato una notifica per quella transazione. Non dimostra che
amount,toocontractaddressnel corpo siano invariati. Se questi campi decidono un pagamento in uscita, verificali sulla catena o rispetto ai valori attesi per l’ordine. - La stessa transazione può arrivare più di una volta, per esempio dopo che hai chiesto il reinvio di una notifica fallita, e ogni copia ha la stessa firma valida. Deduplica su
txid.
I webhook non vengono ritentati automaticamente. Le notifiche fallite sono elencate per catena, e chiedi il reinvio di ciascuna. Solana non ha webhook. Dove i webhook esistono, la firma funziona allo stesso modo su ogni catena.
Come si ruota il segreto senza perdere notifiche?
Un segreto rigenerato ha effetto immediato, quindi l’ordine dei passaggi conta. Fai accettare al gestore due segreti per un breve periodo, poi rigenera:
- Distribuisci una versione del gestore che prova prima il segreto corrente e, se il primo controllo fallisce, un secondo
CG_PERSONAL_SECRET_NEXTfacoltativo. - Rigenera il segreto nel profilo e copia il nuovo valore.
- Inserisci il nuovo valore in
CG_PERSONAL_SECRET_NEXTe ridistribuisci. - Invia un trasferimento di prova sulla testnet e verifica che il gestore lo accetti.
- Dopo un giorno, promuovi il nuovo segreto in
CG_PERSONAL_SECRETe rimuovi il vecchio.
La documentazione non dice quale segreto firma una notifica che reinvii dopo una rotazione. Tieni aperta la finestra a due segreti finché l’elenco delle notifiche fallite non è vuoto.
Che cosa succede se non hai impostato un segreto?
I webhook vengono allora inviati senza l’header X-Signature. Il tuo gestore non deve considerare valida un’assenza di header. Decidi per ambiente: in produzione, rifiuta le richieste senza firma una volta impostato un segreto, mentre in un ambiente di test locale puoi ammetterle. L’header è anche il modo per capire se un segreto è attivo: una notifica senza di esso significa che nessun segreto è impostato sul tuo account.
Dove trovo il riferimento completo?
La guida alla sicurezza dei webhook elenca i passaggi e il codice in quattro linguaggi, e la guida ai webhook spiega come creare webhook e ricevitori.
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.