Verifica dei webhook firmati
Molti servizi appongono una firma ai webhook che inviano, in modo che il destinatario possa verificare che una richiesta provenga effettivamente da loro e non sia stata alterata durante il tragitto. Impostando l’autenticazione di un webhook su HMAC, l’app verifica tale firma prima che qualsiasi dato raggiunga Shopify Flow. Una richiesta che non supera la verifica viene respinta con l’errore 401 e non avvia mai alcun workflow.
Esistono due modi per configurarlo: selezionare il mittente dall’elenco oppure descrivere il modo in cui firma.
Provider integrati
Selezioni il provider nella sezione “Provider di firma” e incolli la relativa chiave di firma. L’app verifica quindi che il provider rispetti le specifiche documentate - intestazione corretta, codifica, contenuto firmato e finestra di riproduzione - pertanto non è necessario configurare altro. Ogni provider dispone di una propria guida alla configurazione, che spazia dalla creazione dell’endpoint alla realizzazione del workflow Shopify Flow.
Ogni guida elenca esattamente quali elementi l’app verifica per quel mittente e dove trovare il suo segreto di firma.
Firma personalizzata: qualsiasi altro mittente
Se il Suo mittente non è presente nell'elenco, selezioni "Firma personalizzata" e descriva in che modo effettua la firma. La documentazione del Suo provider conterrà una riga del tipo:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Quella singola riga fornisce la risposta per ogni campo:
| Ambientazione | Dall'esempio | Cosa significa |
|---|---|---|
| Intestazione della firma | X-Acme-Signature |
L'intestazione recante la firma |
| Algoritmo | hmac_sha256 |
SHA-256, SHA-1 o SHA-512 |
| Codifica | hex |
hex, base64 o base64url |
| Payload firmato | {timestamp}.{body} |
Il testo esatto che è stato firmato |
| Data e ora | un'intestazione del tipo X-Acme-Timestamp |
Dove si sposta il valore di timestamp |
| Tolleranza di riproduzione | 300 secondi | Si prega di respingere le richieste più vecchie di questa |
Il payload firmato
Scriva ciò che il mittente firma utilizzando questi segnaposto:
| Segnalibro | Diventa |
|---|---|
{body} |
Il corpo della richiesta in formato grezzo, byte per byte. Obbligatorio. |
{timestamp} |
Il timestamp contenuto nell'intestazione o nell'intestazione della firma |
{url} |
L'URL di questo webhook, così come lo ha inserito nel campo "mittente" |
{header:name} |
Il valore di un’altra intestazione della richiesta |
Forme comuni: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Utilizzi l’opzione “Parti da un provider” per copiare una corrispondenza simile e modificare solo le parti che differiscono.
Dove si trova la firma
- Semplice: il valore dell'intestazione è la firma, eventualmente preceduta da un prefisso da Lei scelto, come ad esempio
sha256=ov1,. - Chiave = valore: l’intestazione contiene coppie del tipo
t=1700000000,v1=abc.... Si indichi la chiave che contiene la firma (v1), facoltativamente la chiave che contiene il timestamp (t), e se le coppie sono separate da,o;.
Se un'intestazione contiene più firme separate da spazi - cosa che alcuni mittenti fanno quando si alterna un segreto - viene accettata qualsiasi firma che corrisponda.
Il segreto
Di norma, si incolla il codice segreto così come viene visualizzato dal mittente. Alcuni mittenti forniscono una chiave codificata in base64 con un prefisso, ad esempio whsec_...: selezionate l’opzione “codificata in base64” e inserite il prefisso da rimuovere.
Test prima della messa in produzione
Il tester della firma si trova sotto le impostazioni e funziona anche in presenza di modifiche non salvate.
- Inserisca il corpo e le intestazioni di una richiesta reale e prema "Verifica". Verrà visualizzata ogni fase - intestazione individuata, firma letta, timestamp compreso nell'intervallo, payload generato, firme confrontate - insieme al testo esatto che è stato firmato; in questo modo, un'eventuale discrepanza Le consentirà di individuare con precisione il punto in cui si è verificato l'errore, anziché limitarsi a un semplice messaggio del tipo "firma non valida".
- La generazione di un esempio valido produce intestazioni correttamente firmate e un file
curlpronto per l’esecuzione in base alle Sue impostazioni attuali. Se tale richiesta viene accettata, la Sua configurazione risulta coerente dall’inizio alla fine.
Il tester non avvia mai un workflow, non registra nulla nella Cronologia e non viene conteggiato ai fini del Suo piano.
La firma non corrisponde. Cosa dovrei verificare?▾
In questo ordine: il segreto (la causa più comune, tra cui uno spazio in eccesso o la chiave dell’ambiente errata), il payload firmato (un . o : mancante tra il timestamp e il corpo del messaggio), la codifica (hex rispetto a base64) e l’eventuale modifica del corpo del messaggio da parte di un elemento intermedio tra il mittente e l’applicazione. Le firme coprono i byte grezzi, pertanto un proxy che riformatta il JSON le compromette.
Le richieste falliscono con il messaggio "timestamp fuori dai limiti di tolleranza"▾
L'orologio del mittente non è sincronizzato, la richiesta ha subito un ritardo o è stata riprovata con un timestamp obsoleto, oppure l'unità di misura del timestamp è errata. Verifichi se il mittente utilizza secondi, millisecondi o una data ISO.
Il mio mittente necessita innanzitutto di una procedura di verifica▾
Alcuni servizi (Zoom, Dropbox, Asana, Trello, Notion) inviano una richiesta di verifica a cui l’endpoint deve rispondere prima di poter trasmettere qualsiasi evento, ciascuno secondo le proprie modalità. Per questo motivo non sono disponibili come provider “con un solo clic”. Se avete bisogno di uno di essi, contattate l’assistenza indicando il nome del vostro mittente.
La firma è memorizzata da qualche parte?▾
No. Le intestazioni delle firme vengono mascherate nella Cronologia e nell’Inspector delle richieste in tempo reale, poiché una firma può essere riprodotta entro la sua finestra di tolleranza.