Shipment events are triggered when shipments are created, updated, change status, have items assigned, or are deleted.

#TypeScript Interfaces

Copy these interfaces to type your webhook handlers:

/** Base event properties included in all webhook events */
interface BaseEvent {
  /** Unique event identifier (UUID) */
  id: string;
  /** Event type */
  kind: string;
  /** ISO 8601 timestamp */
  time: string;
  /** Transaction identifier for grouping related events */
  transactionId: string;
}
 
/** Shipment status values */
type ShipmentStatus =
  | "onHold"
  | "ready"
  | "pending"
  | "loaded"
  | "shipped"
  | "inTransit"
  | "completed"
  | "canceled";

#shipment.created

Triggered when a new shipment is created.

{
  "id": "evt_abc123",
  "kind": "shipment.created",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "orderId": "ord_789",
  "destination": "Toronto Warehouse"
}

interface ShipmentCreatedEvent extends BaseEvent {
  kind: "shipment.created";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Associated order UUID, if any */
  orderId?: string;
  /** Destination name, if set */
  destination?: string;
}

#shipment.updated

Triggered when any tracked field on a shipment changes. The changes object contains only the fields that changed, each with from and to values.

{
  "id": "evt_abc123",
  "kind": "shipment.updated",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "changes": {
    "status": { "from": "onHold", "to": "shipped" },
    "destination": { "from": null, "to": "Toronto Warehouse" }
  }
}

interface ShipmentChanges {
  status?: { from: ShipmentStatus | null; to: ShipmentStatus | null };
  destination?: { from: string | null; to: string | null };
  transportId?: { from: string | null; to: string | null };
  dueDate?: { from: string | null; to: string | null };
  notes?: { from: string | null; to: string | null };
  [field: string]: { from: unknown; to: unknown } | undefined;
}
 
interface ShipmentUpdatedEvent extends BaseEvent {
  kind: "shipment.updated";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Fields that changed, each with from/to values */
  changes: ShipmentChanges;
}

#shipment.status.changed

Triggered when a shipment's status is updated.

{
  "id": "evt_abc123",
  "kind": "shipment.status.changed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentShortId": "SHP-001",
  "previousShipmentStatus": "pending",
  "currentShipmentStatus": "in_transit"
}

interface ShipmentStatusChangedEvent extends BaseEvent {
  kind: "shipment.status.changed";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
  /** Status before this change */
  previousShipmentStatus: ShipmentStatus;
  /** New status after this change */
  currentShipmentStatus: ShipmentStatus;
}

#Status Values

Status	Description
`onHold`	Shipment on hold, awaiting action
`ready`	Shipment ready to be loaded
`pending`	Shipment pending dispatch
`loaded`	Shipment loaded onto transport
`shipped`	Shipment dispatched
`inTransit`	Shipment in transit to destination
`completed`	Shipment delivered and completed
`canceled`	Shipment cancelled

#shipment.items.assigned

Triggered when items are assigned to a shipment for a specific order.

{
  "id": "evt_abc123",
  "kind": "shipment.items.assigned",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456",
  "shipmentOrderId": "ord_789"
}

interface ShipmentItemsAssignedEvent extends BaseEvent {
  kind: "shipment.items.assigned";
  /** Shipment UUID */
  shipmentId: string;
  /** Order UUID that items were assigned for */
  shipmentOrderId: string;
}

#shipment.deleted

Triggered when a shipment is deleted.

{
  "id": "evt_abc123",
  "kind": "shipment.deleted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "shipmentId": "shp_456"
}

interface ShipmentDeletedEvent extends BaseEvent {
  kind: "shipment.deleted";
  /** Shipment UUID */
  shipmentId: string;
}

#All Shipment Event Types

Union type for handling any shipment event:

type ShipmentEvent =
  | ShipmentCreatedEvent
  | ShipmentUpdatedEvent
  | ShipmentStatusChangedEvent
  | ShipmentItemsAssignedEvent
  | ShipmentDeletedEvent;
 
// Type guard for shipment events
function isShipmentEvent(event: BaseEvent): event is ShipmentEvent {
  return event.kind.startsWith("shipment.");
}
 
// Example webhook handler
async function handleShipmentWebhook(event: ShipmentEvent) {
  switch (event.kind) {
    case "shipment.created":
      console.log(`New shipment created: ${event.shipmentShortId}`);
      break;
 
    case "shipment.updated":
      console.log(`Shipment ${event.shipmentShortId} was updated`);
      break;
 
    case "shipment.status.changed":
      console.log(
        `Shipment ${event.shipmentShortId} changed from ${event.previousShipmentStatus} to ${event.currentShipmentStatus}`
      );
 
      if (event.currentShipmentStatus === "in_transit") {
        // Send tracking notification to customer
      } else if (event.currentShipmentStatus === "delivered") {
        // Update order fulfillment status
      }
      break;
 
    case "shipment.items.assigned":
      console.log(
        `Items assigned to shipment ${event.shipmentId} for order ${event.shipmentOrderId}`
      );
      break;
 
    case "shipment.deleted":
      console.log(`Shipment ${event.shipmentId} was deleted`);
      break;
  }
}

Shipment Events