Node Events

Node events are triggered when flow nodes (locations, stages, containers) are created, 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;
}

/** Node type values */
type NodeType = "stage" | "container" | "bundle";

/** Serialized node object */
interface SerializedNode {
  /** Node UUID */
  id: string;
  /** Node name */
  name: string;
  /** Node type */
  type: NodeType;
  /** Parent node ID (if any) */
  parentId?: string;
  /** Custom attributes */
  attributes?: Record<string, unknown>;
}

/** Change set for node updates */
interface NodeChangeSet {
  /** Fields that were added */
  added?: Record<string, unknown>;
  /** Fields that were updated */
  updated?: Record<string, unknown>;
  /** Fields that were removed */
  removed?: string[];
}

---

node.created

Triggered when a new node is created.

Example

{
  "id": "evt_abc123",
  "kind": "node.created",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "node": {
    "id": "node_456",
    "name": "Cold Storage A",
    "type": "stage",
    "attributes": {
      "temperature": "-20C",
      "capacity": 1000
    }
  }
}

TypeScript

interface NodeCreatedEvent extends BaseEvent {
  kind: "node.created";
  /** Flow UUID */
  flowId: string;
  /** The created node */
  node: SerializedNode;
}

---

node.updated

Triggered when a node’s properties are updated.

Example

{
  "id": "evt_abc123",
  "kind": "node.updated",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "node": {
    "id": "node_456",
    "name": "Cold Storage A (Updated)",
    "type": "stage"
  },
  "changes": {
    "updated": {
      "name": "Cold Storage A (Updated)"
    }
  }
}

TypeScript

interface NodeUpdatedEvent extends BaseEvent {
  kind: "node.updated";
  /** Flow UUID */
  flowId: string;
  /** The updated node */
  node: SerializedNode;
  /** Changes that were made */
  changes: NodeChangeSet;
}

---

node.moved

Triggered when a node is moved to a new parent.

Example

{
  "id": "evt_abc123",
  "kind": "node.moved",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "nodeId": "node_456",
  "fromNode": "node_parent_old",
  "toNode": "node_parent_new"
}

TypeScript

interface NodeMovedEvent extends BaseEvent {
  kind: "node.moved";
  /** Flow UUID */
  flowId: string;
  /** Node UUID that was moved */
  nodeId: string;
  /** Previous parent node UUID */
  fromNode: string;
  /** New parent node UUID */
  toNode: string;
}

---

node.destroyed

Triggered when a node is destroyed.

Example

{
  "id": "evt_abc123",
  "kind": "node.destroyed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "flowId": "flow_123",
  "nodeId": "node_456"
}

TypeScript

interface NodeDestroyedEvent extends BaseEvent {
  kind: "node.destroyed";
  /** Flow UUID */
  flowId: string;
  /** Node UUID that was destroyed */
  nodeId: string;
}

---

All Node Event Types

Union type for handling any node event:

type NodeEvent =
  | NodeCreatedEvent
  | NodeUpdatedEvent
  | NodeMovedEvent
  | NodeDestroyedEvent;

// Type guard for node events
function isNodeEvent(event: BaseEvent): event is NodeEvent {
  return event.kind.startsWith("node.");
}

// Example webhook handler
async function handleNodeWebhook(event: NodeEvent) {
  switch (event.kind) {
    case "node.created":
      console.log(`Node ${event.node.name} created in flow ${event.flowId}`);
      // Sync new location to warehouse management system
      break;

    case "node.updated":
      console.log(`Node ${event.node.id} updated`);
      // Update external systems with new node properties
      break;

    case "node.moved":
      console.log(
        `Node ${event.nodeId} moved from ${event.fromNode} to ${event.toNode}`
      );
      // Update location hierarchy in external systems
      break;

    case "node.destroyed":
      console.log(`Node ${event.nodeId} destroyed`);
      // Remove node from external systems
      break;
  }
}