L'analisi dettagliata delle richieste webhook è un passaggio fondamentale per gli sviluppatori API, gli ingegneri di integrazione, gli addetti al supporto tecnico e i manutentori di sistemi di automazione. Quando si integrano servizi esterni, comprendere l'esatta struttura dei dati trasmessi consente di evitare errori di analisi e di configurare correttamente i sistemi riceventi.
Lo strumento "Ispettore richiesta webhook" permette di incollare il metodo, le intestazioni e il corpo di una richiesta webhook acquisita per esaminarne il formato e generare un comando cURL pronto per il test in locale.
Struttura e inserimento dei dati di una richiesta webhook
Per analizzare una richiesta, lo strumento richiede l'inserimento di tre componenti principali che caratterizzano una trasmissione HTTP:
- Metodo (Metodo): Selezionabile da un elenco predefinito che include POST, PUT, PATCH, GET e DELETE.
- Intestazioni (Intestazioni): Le intestazioni HTTP devono essere inserite una per riga rispettando rigorosamente il formato "Nome: valore". Lo strumento accetta un massimo di 200 righe di intestazione non vuote e un limite dimensionale complessivo di 100.000 caratteri.
- Corpo (Corpo): Rappresenta l'esatto corpo non elaborato (raw body) così come è stato acquisito, prima di qualsiasi operazione di analisi o parsing lato server. Il limite massimo per il corpo è di 1.000.000 di caratteri.
L'inserimento del corpo non elaborato è di fondamentale importanza per il corretto processamento dei webhook. Molti sistemi di sicurezza e di verifica delle firme si basano infatti sull'esatta sequenza di byte trasmessa dal mittente; qualsiasi alterazione, anche minima, invalida il controllo di integrità.
Elaborazione dei formati del corpo e limitazioni
Lo strumento è progettato per rilevare e formattare automaticamente due tipologie di formati di dati comunemente utilizzati nei webhook:
- JSON: I corpi identificati come JSON vengono analizzati tramite la funzione standard
JSON.parse. Questo processo comporta la perdita della formattazione originale, degli spazi vuoti e dell'ordine nativo dei campi, poiché l'oggetto viene ricostruito e ordinato nuovamente durante la formattazione. - Dati di moduli codificati in URL (URL-encoded form data): I parametri della richiesta vengono decodificati e strutturati per una lettura agevole.
Qualsiasi altro formato di dati non rientrante in queste due categorie viene trattato e visualizzato come testo semplice. Se il corpo della richiesta è vuoto, l'interfaccia restituisce la dicitura "(corpo vuoto)".
Identificazione delle firme e dei timestamp
Le intestazioni svolgono un ruolo cruciale nella comunicazione tramite webhook, non solo per definire il tipo di contenuto, ma anche per garantire la sicurezza del trasporto. I mittenti di webhook includono spesso firme crittografiche e timestamp per prevenire attacchi di tipo replay e garantire la provenienza del dato.
Lo strumento analizza le intestazioni fornite alla ricerca di pattern di denominazione comuni associati a firme e timestamp, come ad esempio signature, hmac, digest e i formati di timestamp più diffusi. I campi individuati vengono mostrati nella sezione "Campi della firma". Se non viene rilevata alcuna corrispondenza, l'interfaccia mostra il messaggio "non è stata trovata alcuna firma comune o intestazione del timestamp del webhook.".
Distinzione tra ispezione e verifica dell'autenticità
È fondamentale comprendere la differenza tra l'ispezione visiva di un'intestazione e la reale verifica di sicurezza. L'individuazione di un campo firma non prova in alcun modo che la richiesta sia autentica.
La reale verifica dell'autenticità richiede l'applicazione delle specifiche regole di firma definite dal provider, l'utilizzo di una chiave segreta o pubblica condivisa e il calcolo dell'algoritmo crittografico (come HMAC) direttamente sui byte originali del payload. Questo strumento si limita a identificare la presenza delle intestazioni e non esegue calcoli crittografici, verifiche di algoritmi, controlli sulla finestra di tolleranza temporale (replay window) o validazioni specifiche del provider.
Generazione del comando cURL per test locali
Una volta analizzata la richiesta, lo strumento genera automaticamente un comando cURL configurato per il test in ambiente locale. Questo comando esegue una chiamata di test indirizzata in modo fisso verso l'endpoint locale http://localhost:3000/webhooks.
Il comando cURL generato include tutti i parametri necessari, formattati con i corretti caratteri di escape per la shell, permettendo di replicare la richiesta webhook direttamente sulla propria macchina di sviluppo per scopi di debug e sviluppo del codice di ricezione.
Gestione degli errori e messaggi dell'interfaccia
Durante l'inserimento o l'analisi dei dati, lo strumento esegue controlli di validità e può restituire specifici messaggi di errore in base alla violazione riscontrata:
- Se l'utente tenta di avviare l'ispezione senza aver inserito dati, compare l'errore: "Incolla prima almeno un'intestazione o il corpo della richiesta.".
- Se la lunghezza complessiva delle intestazioni supera il limite stabilito: "Le intestazioni sono troppo lunghe per questo strumento. Rimuovere i valori non correlati o ripetuti.".
- Se il corpo supera il milione di caratteri: "Il corpo è troppo lungo per questo strumento. Mantienilo sotto 1.000.000 di caratteri.".
- Se si inseriscono più di 200 righe di intestazione: "Ci sono troppe righe di intestazione. Mantieni la richiesta a 200 intestazioni o meno.".
- Se una riga delle intestazioni non rispetta la sintassi richiesta, viene indicato il numero di riga specifico: "
‹line›: La riga di intestazione non è valida. Usa Nome: valore.". - Se il corpo presenta una struttura simile al JSON ma contiene errori di sintassi che ne impediscono il parsing: "Il corpo sembra JSON ma non è stato possibile analizzarlo.".
- Se un corpo codificato in URL presenta anomalie nei caratteri di escape: "Il corpo del modulo contiene una percentuale di escape incompleta.".
Riservatezza dei dati e sicurezza del trattamento
La sicurezza dei dati inseriti è garantita dall'architettura di esecuzione dello strumento. Tutto il processo di analisi, formattazione e generazione del comando cURL avviene esclusivamente all'interno del browser dell'utente. I dati della richiesta incollati non vengono caricati su server esterni né salvati da BroBroGo, garantendo la massima riservatezza delle informazioni analizzate.
Domande frequenti (FAQ)
Questa pagina può ricevere una richiamata webhook live?
No. Incolla qui una richiesta acquisita per l'ispezione. La pagina non crea un endpoint pubblico, non riceve callback né invia la richiesta di test generata.
Quali formati del corpo del webhook posso controllare?
I corpi dei moduli con codifica JSON e URL vengono rilevati e formattati. Gli altri corpi rimangono come testo semplice, quindi lo strumento non indovina il contenuto XML, multiparte o binario.
La ricerca di un campo per la firma dimostra che la richiesta sia autentica?
No. Lo strumento mostra solo la firma e le relative intestazioni di timestamp. La vera verifica richiede le esatte regole di firma del mittente, la chiave segreta o pubblica e i byte della richiesta originale.