DOCS
HomePer i fornitori di logistica Webhook

Ascolta gli eventi con i webhook

Ricevi notifiche di eventi in tempo reale per la tua integrazione Zonos.

I webhook offrono a Zonos un modo per notificare in modo proattivo i tuoi sistemi esterni ogni volta che si verificano determinati eventi. Quando si verifica l'evento sottoscritto, Zonos invierà una richiesta HTTP POST all'URL del webhook specificato. Il corpo della richiesta conterrà i dettagli dell'evento, consentendo al tuo sistema di gestire l'evento a livello di codice.

I webhook sono utili per integrare Zonos con altre piattaforme, attivare flussi di lavoro automatizzati e mantenere i dati sincronizzati tra i sistemi in tempo reale. Ad esempio, potresti utilizzare i webhook per:

  • Aggiornare il tuo sistema di gestione degli ordini quando viene creato un ordine in Zonos
  • Avvisare il fornitore di servizi logistici quando una spedizione viene annullata
  • Registrare i cambiamenti di stato degli ordini internazionali a fini di controllo

Tipi di webhook 

Tutti i tipi di webhook disponibili sono inclusi nell'enum WebhookType. I payload di esempio per ciascuno sono disponibili nella nostra guida Tipi di eventi.

Creazione di webhook 

Per creare un webhook tramite API:

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

Importante: Salva il valore di secret quando crei il webhook: viene restituito solo in questa occasione e ti servirà per verificare le firme dei webhook. Consulta Verifica delle firme dei webhook qui sotto.

Modifica i dettagli del webhook 

Per modificare un webhook esistente tramite API:

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

Verifica delle firme dei webhook 

Ogni richiesta webhook inviata da Zonos include un header zonos-signature che ti permette di confermare che la richiesta provenga effettivamente da Zonos e che il payload non sia stato alterato durante il transito.

Il valore dell'header ha il seguente formato:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — l'orario, in millisecondi Unix epoch, in cui la richiesta è stata firmata.
  • hmac — una firma HMAC-SHA256 del corpo grezzo della richiesta JSON, calcolata utilizzando il secret del tuo webhook come chiave e codificata in Base64.

Per verificare una richiesta:

  1. Estrai i valori timestamp e hmac dall'header zonos-signature.
  2. Calcola la tua firma HMAC-SHA256 sul corpo della richiesta grezzo e non elaborato, utilizzando il secret ricevuto al momento della creazione del webhook.
  3. Confronta la firma calcolata con il valore hmac utilizzando un confronto a tempo costante e rifiuta la richiesta se non corrispondono.
  4. Facoltativamente, rifiuta le richieste in cui timestamp risale a più di qualche minuto fa, per proteggerti dalla ripetizione (replay) di una richiesta intercettata. Zonos non applica autonomamente una finestra di consegna, quindi questo controllo spetta a te.
1const crypto = require('crypto');
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(',');
5 const receivedHmac = hmacPart.split('=')[1];
6 
7 const expectedHmac = crypto
8 .createHmac('sha256', secret)
9 .update(rawBody)
10 .digest('base64');
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

Nota: Se hai configurato header personalizzati sul tuo webhook, questi vengono inclusi testualmente in ogni richiesta insieme a zonos-signature.

Visualizza i log dei webhook 

Per visualizzare i log dei webhook tramite API:

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

Questa pagina è stata utile?

Ottieni supporto·Documenti legali·© 2026 Zonos
In questa pagina:
  • Ascolta gli eventi con i webhook
  • Tipi di webhook
  • Creazione di webhook
  • Modifica i dettagli del webhook
  • Verifica delle firme dei webhook
  • Visualizza i log dei webhook