Webhooks
Events pushed to your endpoint instead of polling. Support configures the URL and the secret.
Delivery
A webhook is an HTTPS POST that we send to your endpoint when something happens, so you do not have to poll. Support configures your URL and secret.
- Answer with any
2xxwithin 10 seconds, then process the event asynchronously. - Anything else, including a timeout, is retried up to 10 times, waiting
60 s × 2^nbetween attempts and at most 1 hour. After the last failed attempt the delivery stops (max_retries_exceeded); ask support to resend it. - Every event has
id,type,created_atanddata. Theidis unique: deduplicate on it, because an event can arrive more than once.
Signature
Every delivery is signed. Check the signature before you trust the body.
X-Webhook-Timestampis the Unix time of the signature. Reject a timestamp more than 300 seconds away from your clock: that stops replays.X-Webhook-Signature-V2ist=<timestamp>,v2=<hex>, where the hex is the HMAC-SHA256 of<timestamp>.<raw body>with your webhook secret.- Compute it over the raw body, before any JSON parsing, and compare in constant time.
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
$valid = hash_equals($expected, $v2) && abs(time() - (int) $timestamp) <= 300;
Waybill ready
Coming soon The contract is published ahead of the implementation. This operation is not available yet and its shape may still change.
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).
Authentication: your API key in the X-API-Key header.
Parameters
- Name
X-Webhook-Timestamp- Type
- string
- required
- 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
- required
- 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.
Request body WebhookEvent
- Name
id- Type
- string
- required
- Description
Unique event id; use it to deduplicate retries.
- Name
type- Type
- string
- required
- Description
Event type.
Allowed values:
shipment.waybill_ready,tracking.updated.
- Name
created_at- Type
- string (date-time)
- required
- Description
When the event was created.
- Name
data- Type
- WaybillReadyData | Tracking
- required
- Description
Event payload.
Responses
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"
}
}Models
Objects used by the requests and responses on this page.
WebhookEvent
- Name
id- Type
- string
- required
- Description
Unique event id; use it to deduplicate retries.
- Name
type- Type
- string
- required
- Description
Event type.
Allowed values:
shipment.waybill_ready,tracking.updated.
- Name
created_at- Type
- string (date-time)
- required
- Description
When the event was created.
- Name
data- Type
- WaybillReadyData | Tracking
- required
- Description
Event payload.
WaybillReadyData
- Name
offer_code- Type
- string
- Italian alias:
codice_offerta - Description
Offer code.
- Name
client_reference- Type
- string · nullable
- Italian alias:
custom - Description
Your reference.
- Name
waybill_number- Type
- string
- required
- Italian alias:
lettera_vettura - Description
Waybill number.
- Name
waybill_url- Type
- string (uri)
- required
- Italian alias:
url_ldv - Description
Signed link to the waybill PDF, valid for one hour.
- Name
waybill_url_expires_at- Type
- string (date-time)
- Italian alias:
scade_il - Description
When the link stops working.
- Name
tracking_url- Type
- string (uri)
- Italian alias:
url_tracking - Description
Tracking page.
Tracking
Only shipments of the caller or of the caller's network are visible.
- Name
tracking_number- Type
- string
- required
- Italian alias:
lettera_vettura - Description
Waybill (LDV) number.
- Name
status- Type
- TrackingStatus
- required
- Italian alias:
status - Description
Current status.
- Name
carrier- Type
- string · nullable
- Italian alias:
vettore - Description
Carrier family code.
- Name
shipment_id- Type
- string · nullable
- Italian alias:
id_ordine - Description
Shipment identifier, when known.
- Name
offer_code- Type
- string · nullable
- Italian alias:
codice_offerta - Description
Offer code.
- Name
client_reference- Type
- string · nullable
- Italian alias:
custom - Description
Your reference.
- Name
pickup_booking_code- Type
- string · nullable
- Italian alias:
codice_prenotazione - Description
Pickup booking code.
- Name
tracking_events- Type
- array of TrackingEvent
- required
- Italian alias:
dettagli - Description
Events, oldest first.
- Name
parcels- Type
- array of TrackingParcel
- Italian alias:
parcels - Description
Per-parcel status for multi-parcel shipments.
- Name
carrier_tracking_url- Type
- string (uri) · nullable
- Italian alias:
url_tracking - Description
Carrier public tracking page.
- Name
created_at- Type
- string (date-time)
- Italian alias:
creato_il - Description
When the shipment was created.
- Name
last_update- Type
- string (date-time)
- Italian alias:
ultimo_aggiornamento - Description
Last tracking update.
TrackingStatus
- Name
code- Type
- string
- required
- Italian alias:
codice - Description
Normalised status.
Allowed values:
PENDING,IN_TRANSIT,OUT_FOR_DELIVERY,DELIVERED,EXCEPTION,RETURNED,HELD,NOT_FOUND.
- Name
description- Type
- string
- required
- Italian alias:
descrizione - Description
Human-readable description.
TrackingEvent
- Name
id- Type
- integer
- required
- Italian alias:
id - Description
Progressive event id.
- Name
timestamp- Type
- string (date-time)
- required
- Italian alias:
data - Description
When it happened (carrier local time converted to UTC).
- Name
carrier_status_code- Type
- string
- Italian alias:
status - Description
Carrier event code (for example
PPP,THE,000). See the status-codes reference page.
- Name
description- Type
- string
- required
- Italian alias:
descrizione - Description
Event description.
- Name
note- Type
- string · nullable
- Italian alias:
note - Description
Carrier note.
- Name
location- Type
- string · nullable
- Italian alias:
filiale - Description
Branch or hub.
- Name
signature- Type
- string · nullable
- Italian alias:
firma - Description
Name of who signed for the delivery.
TrackingParcel
- Name
id- Type
- string
- required
- Italian alias:
id - Description
Parcel identifier (sticker).
- Name
status- Type
- TrackingStatus
- required
- Italian alias:
stato - Description
Current status of the parcel.
- Name
carrier_status_code- Type
- string
- Italian alias:
codice_stato_vettore - Description
Carrier code of the current state.
- Name
updated_at- Type
- string (date-time)
- Italian alias:
date - Description
Last update.
- Name
history- Type
- array of object
- Italian alias:
storico - Description
Complete history. Only with
include_parcel_history=true.