tecnico · risposta con fonti
Verifica della firma dei webhook
La verifica della firma dei webhook è un processo di sicurezza in cui il destinatario convalida una firma crittografica allegata a una richiesta HTTP in arrivo. Garantisce che il payload sia stato inviato dal provider attendibile e non sia stato alterato durante il transito.
Definizione
La verifica della firma dei webhook è un meccanismo per autenticare la fonte di un evento webhook. Quando un provider come Resend o SendGrid invia una notifica su un evento email, include un hash del payload firmato con una chiave segreta. Il server ricevente usa la stessa chiave segreta per ricalcolare l'hash e confrontarlo con la firma fornita nell'intestazione della richiesta.
Come funziona
Il provider genera un hash HMAC usando un segreto condiviso e il corpo della richiesta. L'hash viene inviato in un'intestazione, spesso chiamata X-Signature o simile. Il destinatario acquisisce il corpo raw della richiesta e l'intestazione della firma, poi calcola il proprio hash HMAC con il segreto condiviso. Se l'hash calcolato corrisponde al valore dell'intestazione, la richiesta è autentica. Se sono diversi, la richiesta viene rifiutata come non autorizzata.
Perché conta per chi invia
Senza verifica, chiunque conosca l'URL del tuo webhook può inviare dati falsi al tuo server. Questo può portare ad aggiornamenti errati del database, ad esempio segnare come bounce un'email consegnata. Implementare la verifica previene gli attacchi di spoofing e garantisce che la tua applicazione reagisca solo agli eventi legittimi generati dalla tua infrastruttura email.
Note operative
Un errore comune è convertire il corpo della richiesta in un oggetto JSON prima di verificare la firma. Poiché i parser JSON possono modificare gli spazi o l'ordine delle chiavi, la stringa risultante potrebbe non corrispondere al payload originale usato dal provider. Usa sempre il corpo raw della richiesta, non ancora analizzato, per il calcolo HMAC, così eviti fallimenti di verifica.
Esempio di implementazione
In un ambiente Node.js, uno sviluppatore usa il modulo crypto per creare un hash hmac sha256 del corpo raw con il segreto del provider. Il risultato viene poi confrontato con l'intestazione della firma tramite una funzione di confronto a tempo costante, per prevenire i timing attack. SendHQ offre strumenti gratuiti su https://sendhq.cc/tools per gestire le varie configurazioni email che spesso precedono la configurazione dei webhook.
Le domande dei team
Cosa succede se la chiave segreta viene divulgata?
Se la chiave segreta è compromessa, un attaccante può firmare richieste false che il tuo server accetterà come valide. Ruota immediatamente la chiave segreta nella dashboard del provider e aggiorna le variabili d'ambiente del server.
HTTPS rende superflua la verifica della firma?
No. HTTPS cifra i dati in transito e verifica l'identità del server, ma non verifica che il client che invia la richiesta sia proprio il tuo provider email autorizzato.
Perché usare HMAC invece di una semplice chiave API?
Le firme HMAC dimostrano che il contenuto del messaggio non è stato manomesso. Una chiave API statica in un'intestazione dimostra solo che il mittente conosce la chiave, non che il payload sia integro.
Fonti primarie
- Documentazione di Resend — Resend
- Documentazione per sviluppatori di Postmark — Postmark
- Documentazione di SendGrid — Twilio SendGrid