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 2xx within 10 seconds, then process the event asynchronously.
  • Anything else, including a timeout, is retried up to 10 times, waiting 60 s × 2^n between 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_at and data. The id is 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-Timestamp is the Unix time of the signature. Reject a timestamp more than 300 seconds away from your clock: that stops replays.
  • X-Webhook-Signature-V2 is t=<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;

Was this page helpful?

POSTshipment.waybill_ready

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.

Was this page helpful?