Tutto ciò che vale la pena sapere, niente di superfluo.
Come viene costruita la firma
Una costruzione comune forma la stringa canonica come `${timestamp}.${requestBody}`, calcola `HMAC-SHA256(canonical, secret)`, la codifica in esadecimale e invia il digest e il timestamp in un header di firma. Includere il timestamp nel payload firmato impedisce gli attacchi di replay: il tuo endpoint dovrebbe rifiutare i webhook più vecchi di 5 minuti. I nomi degli header e il formato canonico esatto variano da piattaforma a piattaforma, quindi verificali con il tuo provider prima di scrivere il codice di verifica.
Perché le firme HMAC e non quelle RSA?
HMAC è simmetrico, ovvero entrambe le parti condividono un segreto, il che significa che la firma e la verifica sono circa 10.000 volte più veloci di RSA-2048. Per i webhook con un elevato numero di connessioni, dove un singolo SMSC può emettere 50.000 DLR al secondo, la firma RSA sovraccarica la CPU. HMAC-SHA256 su hardware moderno impiega solo pochi microsecondi. Il compromesso: chiunque possieda il segreto può firmare, quindi il segreto va condiviso solo tra la piattaforma e il tuo ambiente, conservato come qualsiasi altra credenziale e ruotabile su richiesta.
Insidie della verifica
Tre bug comuni. Confrontare stringhe con `==` invece di un confronto a tempo costante (attacco di temporizzazione: utilizzare `crypto.timingSafeEqual`). Convalidare la firma dopo aver analizzato il corpo in formato JSON (è necessario verificare i byte grezzi, non una rappresentazione ri-serializzata: il riordino JSON compromette l'hash). Dimenticare la finestra anti-replay del timestamp.
Oltre HMAC
Per gli ambienti regolamentati (banche, sanità), alcune piattaforme supportano anche la consegna dei webhook tramite mTLS: il mittente presenta un certificato client che il tuo load balancer convalida prima che la richiesta raggiunga l'applicazione. È più robusto di HMAC perché lega la consegna a una chiave hardware, ma ne giustifica il costo solo per carichi di lavoro davvero sensibili. Per la maggior parte delle integrazioni, HMAC-SHA256 su HTTPS è la risposta giusta.