Webhook

Un webhook è un indirizzo del tuo sistema che la piattaforma chiama quando succede qualcosa: lo stato di una spedizione cambia, una spedizione viene creata, una giacenza si apre o si chiude. È il modo consigliato per restare aggiornati, al posto di interrogare le API a intervalli regolari.

Registrare un endpoint

Dal pannello

In Impostazioni → Webhooks inserisci l’Endpoint URL, una descrizione facoltativa e scegli gli eventi da ricevere (tieni premuto Ctrl o Cmd per selezionarne più di uno).

Pagina Webhooks: nuovo endpoint ed elenco

Dalle API – `POST /webhooks`


{
  "url": "https://example.com/webhook/spedisci",
  "description": "Gestionale ordini",
  "events": ["tracking.update", "stock.opened", "stock.closed"]
}

Risposta 201:


{
  "id": 12,
  "url": "https://example.com/webhook/spedisci",
  "description": "Gestionale ordini",
  "events": ["tracking.update", "stock.opened", "stock.closed"],
  "isActive": true,
  "secret": "<secret>",
  "createdAt": "2026-09-30T10:00:00+02:00"
}

Il secret è restituito solo alla creazione. Conservalo subito: serve a verificare la firma di ogni invio.

Endpoint	Descrizione
`GET /webhooks`	Gli endpoint registrati
`GET /webhooks/{id}`	Dettaglio di un endpoint
`DELETE /webhooks/{id}`	Elimina l’endpoint e il suo storico
`GET /webhooks/{id}/deliveries`	Gli invii degli ultimi 10 giorni, con esito, codice e corpo della risposta
`POST /webhooks/{id}/test`	Invia subito un evento `tracking.update` reale e firmato

Eventi

Evento	Quando viene inviato
`tracking.update`	Lo stato della spedizione cambia
`shipment.created`	Una spedizione viene creata, da API, dal pannello o dagli ordini
`stock.opened`	Il corriere apre una giacenza sulla spedizione
`stock.closed`	La giacenza si chiude: la spedizione è ripartita, è stata consegnata o è stata resa

Vengono inviati solo gli eventi scelti alla registrazione. Un endpoint registrato senza elenco di eventi riceve tracking.update, stock.opened e stock.closed.

Contenuto degli invii

`tracking.update`


{
  "event": "tracking.update",
  "timestamp": "2026-10-01T08:15:02+02:00",
  "ldv": "3UW0WTQ069239",
  "vector_name": "PosteDeliveryBusiness",
  "order_id": "ORD-1234",
  "client_store_id": null,
  "TrackingDettaglio": [
    { "Data": "01/10/2026 08:12", "Stato": "In transito", "Luogo": "Roma" },
    { "Data": "30/09/2026 10:26", "Stato": "Spedizione generata. In attesa di ritiro.", "Luogo": "Telese Terme" }
  ],
  "statusCode": 3,
  "contractCode": "poste-express",
  "domain": "demo.spedisci.online"
}

Campo	Significato
`ldv`	Numero di spedizione
`order_id`	Il riferimento dell’ordine
`client_store_id`	Il negozio online di provenienza, se presente
`TrackingDettaglio[]`	Gli eventi di tracking, dal più recente: `Data` (`gg/mm/aaaa hh:mm`), `Stato`, `Luogo`
`statusCode`	Codice numerico dello stato: vedi Stato della spedizione
`contractCode`	Codice del contratto
`domain`	La piattaforma che invia l’avviso

`shipment.created`


{
  "event": "shipment.created",
  "timestamp": "2026-09-30T10:26:54+02:00",
  "ldv": "3UW0WTQ069239",
  "shipping_id": 48210,
  "client_id": 1,
  "client_store_id": null,
  "order_id": "ORD-1234",
  "vector_name": "PosteDeliveryBusiness",
  "contractCode": "poste-express",
  "statusCode": 2,
  "domain": "demo.spedisci.online"
}

`stock.opened` e `stock.closed`


{
  "event": "stock.opened",
  "timestamp": "2026-09-29T09:00:12+02:00",
  "ldv": "3UW0WTQ069239",
  "giacenza_id": "<numero della giacenza presso il corriere>",
  "opened_at": "2026-09-29T09:00:00+02:00",
  "stock_id": 912,
  "shipping_id": 48210,
  "statusCode": 6,
  "contractCode": "poste-express",
  "domain": "demo.spedisci.online"
}

stock_id è l’identificativo da usare con /stocks/{id} per leggere la giacenza e inviare le istruzioni.

Verificare la firma

Ogni invio è firmato con il secret dell’endpoint:


Webhook-Timestamp: <unix>
Webhook-Signature: t=<unix>,v1=<HMAC-SHA256 di "<unix>.<corpo>">

Prima di elaborare un invio verifica la firma e la freschezza del timestamp. La procedura completa, con esempi in PHP e Node.js, è in Sicurezza dei webhook (firma HMAC).

Tentativi e disattivazione

Il tuo endpoint deve rispondere con un codice 2xx in tempi brevi: registra l’invio ed elaboralo in un secondo momento.
Su errori di rete e risposte 5xx l’invio viene ritentato 3 volte, dopo 30 secondi, 2 minuti e 5 minuti.
Una risposta 4xx non viene ritentata.
Un endpoint che non risponde 2xx per 72 ore viene disattivato automaticamente e ricevi un avviso via e-mail.
Ogni tentativo è registrato e consultabile con GET /webhooks/{id}/deliveries.

Lo stesso evento può arrivare più di una volta, ad esempio dopo un nuovo tentativo. Rendi l’elaborazione ripetibile: usa ldv, event e timestamp per riconoscere un invio già trattato.