Webhook
Eventi inviati al tuo endpoint al posto del polling. Il supporto configura l'URL e il secret.
Consegna
Un webhook è una POST HTTPS che inviamo al tuo endpoint quando succede qualcosa, così non devi interrogare di continuo. Il supporto configura il tuo URL e il tuo secret.
- Rispondi con un qualsiasi
2xxentro 10 secondi, poi elabora l'evento in modo asincrono. - Qualsiasi altra risposta, timeout compreso, è ritentata fino a 10 volte, attendendo
60 s × 2^ntra i tentativi e al massimo 1 ora. Dopo l'ultimo tentativo fallito la consegna si ferma (max_retries_exceeded); chiedi al supporto di rinviarla. - Ogni evento ha
id,type,created_atedata. L'idè univoco: deduplica su di esso, perché un evento può arrivare più di una volta.
Firma
Ogni consegna è firmata. Verifica la firma prima di fidarti del corpo.
X-Webhook-Timestampè il Unix time della firma. Rifiuta un timestamp lontano più di 300 secondi dal tuo orologio: così si bloccano i replay.X-Webhook-Signature-V2èt=<timestamp>,v2=<hex>, dove l'esadecimale è l'HMAC-SHA256 di<timestamp>.<corpo grezzo>con il tuo webhook secret.- Calcolala sul corpo grezzo, prima di qualsiasi parsing JSON, e confronta in tempo costante.
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
$valid = hash_equals($expected, $v2) && abs(time() - (int) $timestamp) <= 300;
Waybill ready
In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.
Sent to waybill_webhook_url of your account when the waybill of a shipment has been generated (usually within a couple of minutes of ordering). Configure the URL with support. Respond with any 2xx within 10 seconds; failures are retried (see Webhooks in the standard).
Autenticazione: la tua chiave API nell'header X-API-Key.
Parametri
- Name
X-Webhook-Timestamp- Type
- string
- obbligatorio
- Description
Unix time the signature was made. Reject a timestamp more than 300 seconds away from your clock (replay window).
- Name
X-Webhook-Signature-V2- Type
- string
- obbligatorio
- Description
t=<ts>,v2=<hex>: HMAC-SHA256 of<ts>.<raw body>with your webhook secret. Compare in constant time. There is no body-only signature: every signature covers the timestamp.
Corpo della richiesta WebhookEvent
- Name
id- Type
- string
- obbligatorio
- Description
Unique event id; use it to deduplicate retries.
- Name
type- Type
- string
- obbligatorio
- Description
Event type.
Valori ammessi:
shipment.waybill_ready,tracking.updated.
- Name
created_at- Type
- string (date-time)
- obbligatorio
- Description
When the event was created.
- Name
data- Type
- WaybillReadyData | Tracking
- obbligatorio
- Description
Event payload.
Risposte
200Received.
Payload
{
"id": "evt_01JD2X3ZK7Q8",
"type": "shipment.waybill_ready",
"created_at": "2026-12-09T09:37:00+00:00",
"data": {
"offer_code": "offer_example_0003",
"client_reference": "CUSTOM-0000",
"waybill_number": "EX0000000002",
"waybill_url": "https://files.example.com/waybills/EX0000000002.pdf",
"waybill_url_expires_at": "2026-12-09T10:37:00+00:00",
"tracking_url": "https://tracking.example.com/EX0000000002"
}
}Modelli
Oggetti usati dalle richieste e dalle risposte di questa pagina.
WebhookEvent
- Name
id- Type
- string
- obbligatorio
- Description
Unique event id; use it to deduplicate retries.
- Name
type- Type
- string
- obbligatorio
- Description
Event type.
Valori ammessi:
shipment.waybill_ready,tracking.updated.
- Name
created_at- Type
- string (date-time)
- obbligatorio
- Description
When the event was created.
- Name
data- Type
- WaybillReadyData | Tracking
- obbligatorio
- Description
Event payload.
WaybillReadyData
- Name
offer_code- Type
- string
- Alias italiano:
codice_offerta - Description
Offer code.
- Name
client_reference- Type
- string · nullable
- Alias italiano:
custom - Description
Your reference.
- Name
waybill_number- Type
- string
- obbligatorio
- Alias italiano:
lettera_vettura - Description
Waybill number.
- Name
waybill_url- Type
- string (uri)
- obbligatorio
- Alias italiano:
url_ldv - Description
Signed link to the waybill PDF, valid for one hour.
- Name
waybill_url_expires_at- Type
- string (date-time)
- Alias italiano:
scade_il - Description
When the link stops working.
- Name
tracking_url- Type
- string (uri)
- Alias italiano:
url_tracking - Description
Tracking page.
Tracking
Only shipments of the caller or of the caller's network are visible.
- Name
tracking_number- Type
- string
- obbligatorio
- Alias italiano:
lettera_vettura - Description
Waybill (LDV) number.
- Name
status- Type
- TrackingStatus
- obbligatorio
- Alias italiano:
status - Description
Current status.
- Name
carrier- Type
- string · nullable
- Alias italiano:
vettore - Description
Carrier family code.
- Name
shipment_id- Type
- string · nullable
- Alias italiano:
id_ordine - Description
Shipment identifier, when known.
- Name
offer_code- Type
- string · nullable
- Alias italiano:
codice_offerta - Description
Offer code.
- Name
client_reference- Type
- string · nullable
- Alias italiano:
custom - Description
Your reference.
- Name
pickup_booking_code- Type
- string · nullable
- Alias italiano:
codice_prenotazione - Description
Pickup booking code.
- Name
tracking_events- Type
- array of TrackingEvent
- obbligatorio
- Alias italiano:
dettagli - Description
Events, oldest first.
- Name
parcels- Type
- array of TrackingParcel
- Alias italiano:
parcels - Description
Per-parcel status for multi-parcel shipments.
- Name
carrier_tracking_url- Type
- string (uri) · nullable
- Alias italiano:
url_tracking - Description
Carrier public tracking page.
- Name
created_at- Type
- string (date-time)
- Alias italiano:
creato_il - Description
When the shipment was created.
- Name
last_update- Type
- string (date-time)
- Alias italiano:
ultimo_aggiornamento - Description
Last tracking update.
TrackingStatus
- Name
code- Type
- string
- obbligatorio
- Alias italiano:
codice - Description
Normalised status.
Valori ammessi:
PENDING,IN_TRANSIT,OUT_FOR_DELIVERY,DELIVERED,EXCEPTION,RETURNED,HELD,NOT_FOUND.
- Name
description- Type
- string
- obbligatorio
- Alias italiano:
descrizione - Description
Human-readable description.
TrackingEvent
- Name
id- Type
- integer
- obbligatorio
- Alias italiano:
id - Description
Progressive event id.
- Name
timestamp- Type
- string (date-time)
- obbligatorio
- Alias italiano:
data - Description
When it happened (carrier local time converted to UTC).
- Name
carrier_status_code- Type
- string
- Alias italiano:
status - Description
Carrier event code (for example
PPP,THE,000). See the status-codes reference page.
- Name
description- Type
- string
- obbligatorio
- Alias italiano:
descrizione - Description
Event description.
- Name
note- Type
- string · nullable
- Alias italiano:
note - Description
Carrier note.
- Name
location- Type
- string · nullable
- Alias italiano:
filiale - Description
Branch or hub.
- Name
signature- Type
- string · nullable
- Alias italiano:
firma - Description
Name of who signed for the delivery.
TrackingParcel
- Name
id- Type
- string
- obbligatorio
- Alias italiano:
id - Description
Parcel identifier (sticker).
- Name
status- Type
- TrackingStatus
- obbligatorio
- Alias italiano:
stato - Description
Current status of the parcel.
- Name
carrier_status_code- Type
- string
- Alias italiano:
codice_stato_vettore - Description
Carrier code of the current state.
- Name
updated_at- Type
- string (date-time)
- Alias italiano:
date - Description
Last update.
- Name
history- Type
- array of object
- Alias italiano:
storico - Description
Complete history. Only with
include_parcel_history=true.