Webhook Events

Supported Events

parcel.created

Sent when a parcel is created for your business (warehouse receipt).

  • Trigger: parcel creation.
  • Environment: the parcel’s mode (test | live).
  • Retrieve: GET /v1/packages/{parcel_id}.
{
  "event_id": "whd_abc123xyz",
  "event": "parcel.created",
  "data": {
    "parcel_id": "ABC123XYZ",
    "parcel_number": "PCL-12345678",
    "customer_identifier": "YSDX-BONI-234",
    "status": "warehouse",
    "trade_direction": "import",
    "quantity": 1,
    "declared_weight": 5.2,
    "actual_weight": 5.2,
    "length": 40.0,
    "width": 30.0,
    "height": 20.0,
    "volume": 24000.0,
    "mode": "live",
    "origin_country": "China",
    "destination_country": "Nigeria",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "timestamp": 1705312200
}

A booking confirmation does not emit this event — no parcel exists until warehouse receipt.

tracking.{step}

Sent when a tracking milestone changes on a shipment carrying your parcel(s).

  • Trigger: tracking step progress change.
  • Step names are lowercased with underscores (tracking.booking_initiated, tracking.arrived_warehouse, tracking.departed_warehouse, tracking.customs_clearance, tracking.delivered, …).
  • Status values: complete, processing, pending.
  • Retrieve: GET /v1/packages/{parcel_id}/track.
  • Shared shipments: one delivery per affected customer parcel. The parcels array contains only your parcels — never other customers’ parcels, identities, or internal shipment details beyond the shared milestone. Delivery confirmation arrives as your parcel’s own tracking.delivered event, not a shipment-level broadcast.

Ocean parcel milestones

Ocean parcel shipments use port and vessel milestones rather than airport milestones:

  • tracking.arrived_origin_port
  • tracking.loaded_on_vessel
  • tracking.departed_origin_port
  • tracking.arrived_destination_port
  • tracking.delivered
{
  "event_id": "whd_def456uvw",
  "event": "tracking.delivered",
  "data": {
    "tracking_step": {
      "step": "Delivered",
      "status": "complete",
      "completed_on": "15 Jan, 2025"
    },
    "parcels": [{ "parcel_id": "ABC123XYZ", "status": "delivered", "trade_direction": "import" }]
  },
  "timestamp": 1705312200
}