Autenticazione

Chiunque conosca l’URL di un webhook può inviare una richiesta a tale URL; pertanto, è l’autenticazione a impedire che un estraneo attivi i vostri workflow di Shopify Flow. È possibile configurarla per ciascun webhook, nella sezione “Sicurezza” del webhook stesso.

I tre metodi

Metodo	In che modo il chiamante dimostra la propria identità	Lo si utilizza quando
Nessuno	Nulla	Solo a scopo di test - mai in produzione
Token statico	Un valore segreto fisso nell'intestazione di una richiesta	Quasi tutte le integrazioni (n8n, Make, Zapier, il proprio codice)
HMAC SHA-256	Una firma calcolata sulla base della richiesta e di un segreto condiviso	Il mittente firma i propri webhook (Stripe, GitHub, Slack, …)

Token statico

Clicchi sul pulsante "Genera" nel webhook per ottenere un token casuale sicuro, oppure incolli il proprio. Il richiedente lo invia in un'intestazione:

L'editor dei webhook: nome e autenticazione a sinistra; la scheda "Endpoint" con lo stato, l'URL del webhook e l'ID del webhook a destra; in alto: "Anteprima in tempo reale", "Prova" e "Utilizzo" — Un token statico: scelga in che modo il mittente lo trasmette, generi o incolli il token e copi l’URL del webhook dalla scheda “Endpoint”.

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001"}'

Modifica del nome dell'intestazione

Alcuni sistemi possono inviare solo un’intestazione che già utilizzano. Impostate il nome dell’intestazione di autenticazione nelle Impostazioni avanzate e leggeremo il token da tale intestazione anziché da X-Api-Key:

bash

  -H "X-Custom-Auth: your-token"

I nomi delle intestazioni non distinguono tra maiuscole e minuscole. I nomi riservati vengono rifiutati: Host, Authorization, Cookie, X-Forwarded-*, X-Webhook-*, CF-* e simili. Tali nomi vengono impostati o riscritti dai proxy e dai CDN, pertanto un token letto da uno di essi sarebbe controllabile da un malintenzionato.

Dove si sposta il token

Non tutti i mittenti possono aggiungere un’intestazione a loro scelta. In che modo il mittente trasmette il token? Nella scheda “Webhook” sono disponibili quattro campi:

Scelta	Il mittente invia	Lo si utilizza quando
In un'intestazione personalizzata	`X-Api-Key: <token>` o il nome dell’intestazione da Lei scelto	L'impostazione predefinita, e ciò che fanno la maggior parte delle integrazioni
In qualità di token al portatore	`Authorization: Bearer <token>`	Lo strumento presenta un campo "Bearer" o "API-token"
Come nome utente e password	HTTP Basic, con un nome utente a vostra scelta e il token come password	Lo strumento supporta esclusivamente l'autenticazione di base
Nell'URL	`?token=<token>` o il nome del parametro da Lei scelto	Il mittente può richiamare solo un URL semplice e non può impostare le intestazioni

Authorization Il nome dell'intestazione personalizzata rimane volutamente riservato: “Bearer” e “Basic” sono i metodi supportati per il suo utilizzo ed entrambi vengono gestiti automaticamente. Un’autenticazione di tipo 401 con questi due metodi comporta inoltre l’invio dell’intestazione WWW-Authenticate, poiché diversi client HTTP inviano le credenziali solo dopo aver ricevuto una richiesta di autenticazione.

L'opzione URL è la meno sicura delle quattro - gli URL finiscono nei log, nei referrer e nella cronologia del browser - pertanto la utilizzi solo quando il mittente non le lascia altra scelta. L'app mostra l'URL completo contenente il token e maschera tale parametro ovunque memorizzi la richiesta.

HMAC SHA-256

Il mittente calcola una firma sulla richiesta utilizzando un segreto condiviso; noi la ricalcoliamo e la confrontiamo. Una richiesta trapelata non può essere riprodotta con contenuti alterati, poiché il corpo del messaggio non corrisponde più alla firma.

Impostazioni predefinite del fornitore

Selezioni il Suo mittente nella sezione “Fornitore di firme” e noi effettueremo la verifica utilizzando lo schema esatto di tale fornitore: nome dell’intestazione, codifica, oggetto della firma e durata di validità della firma. Incolli il segreto di firma dalla relativa dashboard e il gioco è fatto.

Sono disponibili 22 provider integrati, ciascuno con la propria guida alla configurazione: Calendly, Customer.io, GitHub, Lemon Squeezy, Linear, Mollie, Paddle, Paystack, Razorpay, Sanity, Sendcloud, Sentry, Shopify, Slack, Square, Webhook standard (OpenAI, Supabase), Stripe, Svix (Clerk, Resend), Typeform, Vercel, WooCommerce e Zendesk. Se il Suo provider non è presente nell’elenco, descriva in che modo effettua l’autenticazione utilizzando uno schema personalizzato.

Si veda Verifica dei webhook firmati per l'elenco completo, l'opzione personalizzata e lo strumento di verifica delle firme integrato.

Un webhook con autenticazione HMAC e Stripe come fornitore di firma, che illustra il campo “segreto di firma”, cosa viene verificato e i passaggi per collegare Stripe — Un mittente autenticato, in questo caso Stripe: selezionate il fornitore, incollate il suo segreto di firma e l’editor mostrerà quali campi sono selezionati e come effettuare la connessione.

HMAC generico

In assenza di impostazioni predefinite e di schemi personalizzati, utilizziamo il nostro: il chiamante invia unX-Signature, ovvero l'HMAC-SHA256 dei valori dell'intestazione X-Webhook-* utilizzando la chiave segreta di firma.

bash

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Data: value1value2" \
  -H "X-Signature: <hmac-sha256 of the X-Webhook-* values>" \
  -d '{"data":"payload"}'

Come si presenta un rifiuto

Un’autenticazione non riuscita restituisce un codice di errore 401 con un corpo JSON che ne indica il motivo; si veda Cronologia e risoluzione dei problemi per l’elenco completo dei codici. Le chiamate respinte continuano ad apparire nel Live Request Inspector mentre si sta modificando il webhook, in modo da poter vedere esattamente il motivo per cui una richiesta è stata respinta.

Rotazione della chiave segreta senza tempi di inattività

La modifica di un segreto in un’unica operazione comporta che ogni richiesta firmata con il segreto precedente risulti non valida fino a quando il mittente non si sia adeguato. La rotazione del segreto tramite il webhook evita tale problema: esso conserva un secondo segreto valido che viene accettato insieme a quello principale, sia per il token statico che per ogni schema di firma.

Inserisca la nuova password in “Seconda password valida” e salvi. Ora entrambe le password sono accettate.
Configuri il mittente con il nuovo segreto.
Clicchi su "Promuovi", operazione che sposta l'elemento nel campo principale e cancella quello secondario, quindi salvi.

Nessuna richiesta viene respinta in nessuna fase. Il secondo segreto viene memorizzato esattamente come quello principale e non viene mai restituito dall’API: viene indicato solo se è stato impostato o meno.

Mantenere il segreto al sicuro

Il token non viene mai restituito dalla nostra API REST né dal server MCP a nessun livello di accesso - essi Indica solo se uno di essi è impostato. Si veda API per sviluppatori e MCP.
I dati sono crittografati quando sono inattivi.
La rotazione ha effetto immediato, pertanto si raccomanda di utilizzare Shopify Flow sopra indicato anziché sovrascrivendo il campo principale.
La cronologia delle invocazioni memorizzata nasconde l’intestazione di autenticazione, le credenziali Basic e il token dell’URL, Pertanto, uno screenshot della cronologia non comporta la divulgazione dei Suoi dati riservati.

Restringere ulteriormente il campo

L'autenticazione dimostra che il chiamante conosce il segreto. La verifica della provenienza (Elenchi di indirizzi IP autorizzati) limita la provenienza da cui può provenire una chiamata e può essere combinata con una qualsiasi delle modalità sopra indicate.