Shipment Events

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 =
  | "pending"
  | "picking"
  | "packed"
  | "in_transit"
  | "delivered"
  | "cancelled";

---

shipment.created

Triggered when a new shipment is created.

Example

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

TypeScript

interface ShipmentCreatedEvent extends BaseEvent {
  kind: "shipment.created";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
}

---

shipment.updated

Triggered when shipment details are updated.

Example

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

TypeScript

interface ShipmentUpdatedEvent extends BaseEvent {
  kind: "shipment.updated";
  /** Shipment UUID */
  shipmentId: string;
  /** Human-readable shipment ID (e.g., "SHP-001") */
  shipmentShortId: string;
}

---

shipment.status.changed

Triggered when a shipment’s status is updated.

Example

{
  "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"
}

TypeScript

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
pending	Shipment created
picking	Items being picked
packed	Shipment packed
in_transit	Shipment in transit
delivered	Shipment delivered
cancelled	Shipment cancelled

---

shipment.items.assigned

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

Example

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

TypeScript

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.

Example

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

TypeScript

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;
  }
}