Come verificare una firma webhook HMAC
Indichi l'algoritmo HMAC, ad esempio HMAC-SHA256, e l'intestazione che contiene la firma: otterrà 8 passaggi in ordine, dalla conservazione del corpo grezzo al confronto a tempo costante, fino al controllo dei messaggi ripetuti. Gratis nel Suo browser.
- Gratis
- Funziona nel suo browser
- Senza registrazione
- I suoi dati restano sul dispositivo
Esegui gratis nel browser
Questa capacità converte l’algoritmo HMAC e l’intestazione del fornitore in una lista precisa e ordinata.
Che cosa dimostra una firma HMAC
Chi invia la notifica calcola un HMAC con un segreto condiviso sui byte esatti del messaggio e mette il risultato in un'intestazione. Alla ricezione, il Suo sistema rifà lo stesso calcolo: prende il corpo grezzo così come è arrivato, aggiunge l'orario firmato o il prefisso richiesto dal fornitore, applica l'algoritmo indicato e codifica il risultato come prevede la documentazione, di solito in esadecimale o Base64. Se le due firme coincidono, il messaggio è stato prodotto da qualcuno che conosce il segreto. Questo non dimostra che sia recente né che non sia già stato elaborato: per questo seguono la finestra di tolleranza sull'orario e l'archivio degli identificativi di evento già accettati.
Errori tipici e quando usare i passaggi
Il guasto più frequente avviene prima del calcolo: il sistema legge e riordina il corpo, cambia spazi, ordine o fine riga, e la firma corretta non combacia più. Altri errori classici sono accettare un'intestazione vuota o duplicata, confrontare con una normale uguaglianza e troncare o completare valori di lunghezza diversa invece di rifiutarli. Usi questi passaggi quando realizza o rivede un ricevitore e quando prepara un piano di verifiche con corpi alterati, orari scaduti, segreti sbagliati ed eventi ripetuti. La documentazione del fornitore resta il riferimento per il formato dell'intestazione.
Parta dai byte firmati dal fornitore
Conservi esattamente i byte ricevuti prima dell’analisi. Legga l’intestazione indicata ignorando le maiuscole nel nome, ma ne convalidi rigorosamente il valore. Segua la grammatica del fornitore, rifiuti valori assenti, vuoti, duplicati o malformati e custodisca il segreto in un gestore protetto, perché è una credenziale sensibile.
Ricostruisca, calcoli e confronti nell’ordine corretto
Ricostruisca esattamente il messaggio firmato: solo corpo grezzo oppure data, separatore e corpo. Rispetti l’ordine e la codifica documentati. Calcoli HMAC con il segreto e l’algoritmo normalizzato, quindi codifichi il risultato come richiesto.
Decodifichi le firme in byte di pari lunghezza e usi un confronto a tempo costante. Una codifica errata o lunghezze diverse comportano il rifiuto, poiché non è lecito adattare i valori.
Consideri la crittografia una parte dell’accettazione
Un HMAC uguale prova la conoscenza del segreto, non la freschezza o l’unicità. Applichi la tolleranza temporale, registri gli identificatori accettati e renda idempotente l’elaborazione. Ruoti i segreti secondo la sovrapposizione documentata.
Rifiuti prima di accodare, restituisca un errore generico e registri solo codici sicuri. Provi corpi modificati, date scadute, intestazioni errate, segreti sbagliati e replay, così la verifica sarà più affidabile.
Casi d'uso
Controllare un’integrazione esistente
Verifichi l’ordine di acquisizione, HMAC, confronto sicuro e difesa dai replay.
Preparare test di sicurezza
Definisca test negativi per intestazioni assenti, corpi alterati, firme errate, date scadute e replay.
Domande frequenti
Quali algoritmi riconosce?
HMAC-SHA1, HMAC-SHA256, HMAC-SHA384 e HMAC-SHA512. Gli altri causano un errore di input.
Perché conservare il corpo grezzo?
L’analisi e la riserializzazione possono cambiarne i byte e invalidare una firma corretta.
Un HMAC valido impedisce i replay?
No. Verifichi la data firmata e deduplichi gli identificatori forniti.
Perché confrontare la firma a tempo costante?
Perché un confronto normale può rivelare, dai tempi di risposta, quanta parte della firma coincideva. Converta entrambi i valori in byte di uguale lunghezza e usi un confronto sicuro rispetto ai tempi; una differenza di lunghezza o di decodifica conta come verifica fallita.
Devo inserire il mio segreto o il messaggio ricevuto?
No. L'elenco dei passaggi richiede solo l'algoritmo HMAC e il nome dell'intestazione di firma, quindi segreto, messaggio e firma restano all'interno del Suo ricevitore.
Strumenti correlati
Per sviluppatori — accesso via API
Tutto quello che vedi in questa pagina è disponibile anche via API. Questa sezione è per i team che vogliono integrarlo nei propri sistemi; chi non ne ha bisogno può semplicemente usare lo strumento qui sopra.
Endpoint
Autenticazione con Bearer token: un POST mette in coda l'attività e il risultato arriva via webhook o link firmato.
Chiamala dal tuo stack
curl -X POST https://api.kit.forhosting.com/security/webhook-signature-verify-steps \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}'const res = await fetch("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"algorithm": "HMAC-SHA256",
"header_name": "X-Webhook-Signature"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/security/webhook-signature-verify-steps",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"algorithm": "HMAC-SHA256",
"header_name": "X-Webhook-Signature"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/security/webhook-signature-verify-steps", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"algorithm":"HMAC-SHA256","header_name":"X-Webhook-Signature"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/security/webhook-signature-verify-steps", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Esempio di richiesta
{
"algorithm": "HMAC-SHA256",
"header_name": "X-Webhook-Signature"
}Esempio di risposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "security.webhook_signature_verify_steps",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}L'API è asincrona: ricevi subito un task_id e puoi fare polling fino a 1 richiesta al secondo.
Prezzi
Prezzo pubblicato, senza token né crediti. Se l'attività fallisce, non paghi.
Errori
| HTTP | Codice | Significato |
|---|---|---|
401 | unauthorized | Chiave API mancante o non valida: controlla l'header Authorization. |
402 | insufficient_balance | Credito esaurito: ricarica per continuare a eseguire attività. |
404 | unknown_type | Tipo di attività sconosciuto: controlla il campo type della richiesta. |
429 | rate_limited | Troppe richieste in poco tempo: rallenta e riprova tra qualche secondo. |
Note tecniche
La verifica delle firme webhook spesso fallisce ai confini: il framework modifica il corpo, l’intestazione viene interpretata senza rigore o il confronto ordinario rivela informazioni temporali. Non richiede payload, segreto o firma. Usi il risultato per implementare o controllare l’endpoint e verifichi il formato temporale, la codifica e la tolleranza ai replay nella documentazione ufficiale.
Parta dai byte firmati dal fornitore
Analizzare e riserializzare JSON può cambiare spazi, ordine, escape, Unicode o fine riga.
Casi di integrazione
Implementare un nuovo endpoint webhook
Converta l’algoritmo e l’intestazione in una lista verificabile prima di programmare.
Domande tecniche
Questo strumento verifica un webhook reale?
No. Produce passaggi e non richiede mai payload, segreto o firma.
Devo inviare il segreto webhook?
No. Servono solo l’algoritmo e l’intestazione; conservi il segreto nell’ambiente protetto.
Quanto costa una richiesta API?
Ogni richiesta costa $0.002. L’implementazione deterministica opera nel browser senza inviare segreti.