Transfer Events

Transfer events are triggered when internal transfers change status.

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

/** Transfer status values */
type TransferStatus =
  | "pending"
  | "in_progress"
  | "completed"
  | "cancelled";

---

transfer.status.changed

Triggered when a transfer’s status is updated.

Example

{
  "id": "evt_abc123",
  "kind": "transfer.status.changed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "transferId": "tfr_456",
  "transferShortId": "TFR-001",
  "previousTransferStatus": "pending",
  "currentTransferStatus": "in_progress"
}

TypeScript

interface TransferStatusChangedEvent extends BaseEvent {
  kind: "transfer.status.changed";
  /** Transfer UUID */
  transferId: string;
  /** Human-readable transfer ID (e.g., "TFR-001") */
  transferShortId: string;
  /** Status before this change */
  previousTransferStatus: TransferStatus;
  /** New status after this change */
  currentTransferStatus: TransferStatus;
}

Status Values

Status	Description
pending	Transfer created, awaiting processing
in_progress	Transfer in progress
completed	Transfer completed successfully
cancelled	Transfer cancelled

---

All Transfer Event Types

Union type for handling any transfer event:

type TransferEvent = TransferStatusChangedEvent;

// Type guard for transfer events
function isTransferEvent(event: BaseEvent): event is TransferEvent {
  return event.kind.startsWith("transfer.");
}

// Example webhook handler
async function handleTransferWebhook(event: TransferEvent) {
  switch (event.kind) {
    case "transfer.status.changed":
      console.log(
        `Transfer ${event.transferShortId} changed from ${event.previousTransferStatus} to ${event.currentTransferStatus}`
      );

      if (event.currentTransferStatus === "completed") {
        // Update inventory locations
      } else if (event.currentTransferStatus === "cancelled") {
        // Revert any partial changes
      }
      break;
  }
}