Webhooks

Webhooks push events to your HTTP endpoint as they happen, so you do not need to poll the tracking endpoints. Every delivery is signed with HMAC-SHA256 so you can verify it comes from Spedisci.online.

Endpoints can be managed through the API (below) or from the Webhooks page of the web interface; both use the same signature and events.

Events

Only the events listed in events at registration are delivered. An endpoint registered from the web interface without a list receives tracking.update, stock.opened and stock.closed.

Managing endpoints

Register an endpoint

{
  "url": "https://erp.acme.it/webhooks/spedisci",
  "description": "ERP sync",
  "events": ["tracking.update", "shipment.created", "stock.opened", "stock.closed"]
}

{
  "id": 412,
  "url": "https://erp.acme.it/webhooks/spedisci",
  "description": "ERP sync",
  "events": ["tracking.update", "shipment.created", "stock.opened", "stock.closed"],
  "isActive": true,
  "secret": "whsec_9f3c1e8a7b2d4c6e5f0a1b2c3d4e5f60",
  "createdAt": "2026-09-03T09:00:00+02:00"
}

Delivery

Each event is one HTTP POST to your endpoint with a JSON body and these headers:

Deliveries are sent asynchronously, independently for each endpoint, with a 10-second timeout:

• A 2xx answer marks the delivery as success.
• Network errors and 5xx answers are retried 3 times in total, after 30 seconds, 2 minutes and 5 minutes.
• A 4xx answer is not retried: it is the endpoint’s final word and is only logged.
• An endpoint with no 2xx answer for 72 hours is deactivated automatically (isActive: false) and the client is notified by email. Re-enable it from the web interface, or delete and register it again.

Answer quickly (ideally 200 before processing) and process the event asynchronously. Events may occasionally arrive more than once or out of order: use ldv + timestamp to deduplicate.

Verifying the signature

1. Read Webhook-Timestamp and Webhook-Signature; reject the request if either is missing.
2. Reject it if the timestamp is older than 300 seconds (replay protection).
3. Compute HMAC-SHA256("<timestamp>.<raw body>", secret) as lowercase hex.
4. Compare it to the v1= value with a timing-safe comparison.

const crypto = require('crypto')
 
function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['webhook-timestamp']
  const signature = headers['webhook-signature']
  if (!timestamp || !signature) return false
 
  if (Math.floor(Date.now() / 1000) - parseInt(timestamp, 10) > 300) return false
 
  const v1 = signature.split(',').find(p => p.startsWith('v1='))?.slice(3)
  if (!v1) return false
 
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

function verifyWebhook(string $rawBody, array $headers, string $secret): bool
{
    $timestamp = $headers['Webhook-Timestamp'] ?? null;
    $signature = $headers['Webhook-Signature'] ?? null;
    if (!$timestamp || !$signature) {
        return false;
    }
    if (time() - (int) $timestamp > 300) {
        return false;
    }
    if (!preg_match('/v1=([a-f0-9]+)/', $signature, $m)) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $m[1]);
}

import hmac, hashlib, time
 
def verify_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    timestamp = headers.get('Webhook-Timestamp')
    signature = headers.get('Webhook-Signature', '')
    if not timestamp or not signature:
        return False
    if time.time() - int(timestamp) > 300:
        return False
    v1 = next((p[3:] for p in signature.split(',') if p.startswith('v1=')), None)
    if not v1:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Payloads

All payloads carry event, timestamp (ISO 8601), ldv (tracking number), contractCode, statusCode (numeric shipment status) and domain (the platform host).

tracking.update

{
  "event": "tracking.update",
  "timestamp": "2026-09-04T11:50:12+02:00",
  "ldv": "DEMO05407027",
  "vector_name": "Brt",
  "order_id": "ORD-1234",
  "client_store_id": null,
  "TrackingDettaglio": [
    { "Data": "04/09/2026 11:42", "Stato": "Consegnata", "Luogo": "Roma" },
    { "Data": "04/09/2026 08:15", "Stato": "In consegna", "Luogo": "Roma" },
    { "Data": "03/09/2026 10:26", "Stato": "Spedizione generata", "Luogo": "Milano" }
  ],
  "statusCode": 5,
  "contractCode": "brt-standard",
  "domain": "demo.spedisci.online"
}

This payload is identical to the one sent by the legacy webhooks, with event and timestamp added in front: an endpoint written for API v2 keeps working.

shipment.created

{
  "event": "shipment.created",
  "timestamp": "2026-09-03T10:26:55+02:00",
  "ldv": "DEMO05407027",
  "shipping_id": 4454058,
  "client_id": 1520,
  "client_store_id": null,
  "order_id": "ORD-1234",
  "vector_name": "Brt",
  "contractCode": "brt-standard",
  "statusCode": 0,
  "domain": "demo.spedisci.online"
}

stock.opened / stock.closed

{
  "event": "stock.opened",
  "timestamp": "2026-09-05T09:15:31+02:00",
  "ldv": "DEMO05407027",
  "giacenza_id": "GIA-2026-000123",
  "opened_at": "2026-09-05T09:12:00+02:00",
  "stock_id": 9812,
  "shipping_id": 4454058,
  "statusCode": 6,
  "contractCode": "brt-standard",
  "domain": "demo.spedisci.online"
}

stock_id is the id to use with GET /stocks/{id} and POST /stocks/{id}/actions. giacenza_id is the carrier dossier: after a release the carrier can reissue the LDV and open a second dossier on the same parcel.

Delivery log

GET /webhooks/{id}/deliveries — paginated, last 10 days

{
  "data": [
    {
      "id": 99120,
      "event": "tracking.update",
      "status": "success",
      "responseCode": 200,
      "responseBody": "ok",
      "payload": { "event": "tracking.update", "ldv": "DEMO05407027", "statusCode": 5 },
      "createdAt": "2026-09-04T11:50:13+02:00"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 50, "to": 1, "total": 1 }
}

status is success or failed; responseCode is 0 on connection errors, with the error in responseBody (truncated to 1000 characters).

Testing an endpoint

POST /webhooks/{id}/test — rate limit 5 / min

Sends a real tracking.update built from your most recent shipment in transit, signed with the endpoint’s secret, and returns the outcome:

{
  "delivered": true,
  "responseCode": 200,
  "responseBody": "ok",
  "payload": { "event": "tracking.update", "ldv": "DEMO05407027", "statusCode": 3 }
}

Answers 404 not_found when the account has no shipment in transit yet.