Inventory Events

Inventory events are triggered when inventory items are received, produced, modified, moved, or destroyed.

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

/** Entity object included in inventory events */
interface Entity {
  /** Entity UUID */
  id: string;
  /** Entity name/code (e.g., "BATCH-001") */
  name: string;
  /** Product UUID */
  productId: string;
  /** Quantity */
  quantity?: number;
  /** Custom attributes */
  attributes?: Record<string, unknown>;
}

/** Node/location reference */
interface Node {
  /** Node UUID */
  id: string;
  /** Node name (e.g., "Receiving Bay 1") */
  name: string;
  /** Node type */
  type: "stage" | "container" | "bundle";
}

/** Change tracking for inventory modifications */
interface EntityChanges {
  attributes: {
    add: Array<{ key: string; value: unknown }>;
    updated: Array<{ key: string; value: unknown }>;
    removed: string[];
  };
  correlations: {
    add: string[];
    updated: string[];
    removed: string[];
  };
  spawns: {
    add: string[];
  };
  status: { from: string; to: string } | null;
}

inventory.received

Triggered when inventory is received into the system.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.received",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entity": {
    "id": "ent_456",
    "name": "BATCH-001",
    "productId": "prod_789",
    "quantity": 100,
    "attributes": {}
  },
  "node": {
    "id": "node_abc",
    "name": "Receiving Bay 1",
    "type": "stage"
  }
}

interface InventoryReceivedEvent extends BaseEvent {
  kind: "inventory.received";
  flowId: string;
  entity: Entity;
  node: Node;
}

inventory.produced

Triggered when inventory is created via a transformation (production).

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.produced",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entity": {
    "id": "ent_456",
    "name": "FINISHED-001",
    "productId": "prod_789",
    "quantity": 50
  },
  "node": {
    "id": "node_abc",
    "name": "Production Line 1",
    "type": "stage"
  }
}

interface InventoryProducedEvent extends BaseEvent {
  kind: "inventory.produced";
  flowId: string;
  entity: Entity;
  node: Node;
}

inventory.modified

Triggered when inventory attributes, correlations, quantity, or status are updated. Multiple entity modifications from the same transaction are batched into a single event (up to 100 entities per event). Large transactions may produce multiple events.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.modified",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entities": [
    {
      "entityId": "ent_456",
      "entityName": "BATCH-001",
      "changes": {
        "attributes": {
          "add": [{ "key": "temperature", "value": "4C" }],
          "updated": [],
          "removed": []
        },
        "correlations": {
          "add": [],
          "updated": [],
          "removed": []
        },
        "spawns": { "add": [] },
        "status": null
      }
    },
    {
      "entityId": "ent_457",
      "entityName": "BATCH-002",
      "changes": {
        "attributes": {
          "add": [],
          "updated": [{ "key": "location", "value": "Cold Storage" }],
          "removed": []
        },
        "correlations": {
          "add": [],
          "updated": [],
          "removed": []
        },
        "spawns": { "add": [] },
        "status": { "from": "active", "to": "on_hold" }
      }
    }
  ]
}

interface InventoryModifiedEvent extends BaseEvent {
  kind: "inventory.modified";
  flowId: string;
  entities: Array<{
    entityId: string;
    entityName: string;
    changes: EntityChanges;
  }>;
}

inventory.moved

Triggered when inventory is moved to a new location (stage or container).

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.moved",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entity": {
    "id": "ent_456",
    "name": "BATCH-001",
    "productId": "prod_789"
  },
  "from": {
    "id": "node_abc",
    "name": "Receiving Bay 1",
    "type": "stage"
  },
  "to": {
    "id": "node_def",
    "name": "Cold Storage",
    "type": "stage"
  }
}

interface InventoryMovedEvent extends BaseEvent {
  kind: "inventory.moved";
  flowId: string;
  entity: Entity;
  from: Node;
  to: Node;
}

inventory.bundled

Triggered when inventory is moved into a bundle.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.bundled",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entity": {
    "id": "ent_456",
    "name": "BATCH-001",
    "productId": "prod_789"
  },
  "from": {
    "id": "node_abc",
    "name": "Staging Area",
    "type": "stage"
  },
  "to": {
    "id": "bundle_def",
    "name": "PALLET-001",
    "type": "bundle"
  }
}

interface InventoryBundledEvent extends BaseEvent {
  kind: "inventory.bundled";
  flowId: string;
  entity: Entity;
  from: Node;
  to: Node;
}

inventory.destroyed

Triggered when inventory is destroyed or consumed.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.destroyed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entityId": "ent_456"
}

interface InventoryDestroyedEvent extends BaseEvent {
  kind: "inventory.destroyed";
  flowId: string;
  entityId: string;
}

inventory.wasted

Triggered when inventory is marked as waste.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.wasted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entityId": "ent_456",
  "reason": "Expired"
}

interface InventoryWastedEvent extends BaseEvent {
  kind: "inventory.wasted";
  flowId: string;
  entityId: string;
  reason?: string;
}

inventory.merged

Triggered when multiple inventory items are merged into a single item.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.merged",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "mergedEntity": {
    "id": "ent_789",
    "name": "MERGED-001",
    "productId": "prod_123",
    "quantity": 200
  },
  "sourceEntityIds": ["ent_456", "ent_457"],
  "sourceEntityNames": ["BATCH-001", "BATCH-002"],
  "node": {
    "id": "node_abc",
    "name": "Merge Station",
    "type": "stage"
  }
}

interface InventoryMergedEvent extends BaseEvent {
  kind: "inventory.merged";
  flowId: string;
  mergedEntity: Entity;
  sourceEntityIds: string[];
  sourceEntityNames: string[];
  node: Node;
}

inventory.merge.reverted

Triggered when a merge operation is reverted, restoring the original items.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.merge.reverted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "revertedEntityId": "ent_789",
  "restoredEntityIds": ["ent_456", "ent_457"],
  "restoredEntityNames": ["BATCH-001", "BATCH-002"],
  "node": {
    "id": "node_abc",
    "name": "Merge Station",
    "type": "stage"
  }
}

interface InventoryMergeRevertedEvent extends BaseEvent {
  kind: "inventory.merge.reverted";
  flowId: string;
  revertedEntityId: string;
  restoredEntityIds: string[];
  restoredEntityNames: string[];
  node: Node;
}

inventory.restored

Triggered when inventory is restored via deconstruction.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.restored",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "restoredEntityId": "ent_456",
  "sourceEntityId": "ent_789",
  "sourceEntityName": "FINISHED-001",
  "node": {
    "id": "node_abc",
    "name": "Deconstruction Station",
    "type": "stage"
  }
}

interface InventoryRestoredEvent extends BaseEvent {
  kind: "inventory.restored";
  flowId: string;
  restoredEntityId: string;
  sourceEntityId: string;
  sourceEntityName: string;
  node: Node;
}

inventory.restored_from_history

Triggered when inventory is restored from a historical snapshot.

Example
TypeScript

{
  "id": "evt_abc123",
  "kind": "inventory.restored_from_history",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "entityId": "ent_456",
  "previousStatus": "destroyed",
  "fromNodeId": "node_abc",
  "toNodeId": "node_def",
  "quantity": "10 kg",
  "reason": "Incorrect destruction"
}

interface InventoryRestoredFromHistoryEvent extends BaseEvent {
  kind: "inventory.restored_from_history";
  entityId: string;
  previousStatus: string;
  fromNodeId?: string;
  toNodeId: string;
  quantity: string;
  reason: string;
}

All Inventory Event Types

Union type for handling any inventory event:

type InventoryEvent =
  | InventoryReceivedEvent
  | InventoryProducedEvent
  | InventoryModifiedEvent
  | InventoryMovedEvent
  | InventoryBundledEvent
  | InventoryDestroyedEvent
  | InventoryWastedEvent
  | InventoryMergedEvent
  | InventoryMergeRevertedEvent
  | InventoryRestoredEvent
  | InventoryRestoredFromHistoryEvent;

// Type guard for inventory events
function isInventoryEvent(event: BaseEvent): event is InventoryEvent {
  return event.kind.startsWith("inventory.");
}