container.status.updated

Overview

Fired when a container transitions to a new milestone status. This is the most commonly used webhook event and represents significant lifecycle transitions such as vessel departure, arrival, discharge, availability, delivery, and empty return.

When This Event Fires

A new milestone has been recorded in the container's history, causing the top-level status field to change. Milestones represent major lifecycle transitions — for example, moving from LOADED to VESSEL_DEPARTED, or from DISCHARGED to AVAILABLE.

📘

This event only fires for milestone transitions. Minor history updates (e.g. a backfilled date correction) that do not change the current status will fire container.history.updated instead.

Milestones that trigger this event

The following statuses are considered milestones. A transition to any of these will fire the event:

Payload Structure

{
  "event": "container.status.updated",
  "data": { /* IContainerVoyageResponse — full container snapshot */ },
  "changes": {
    "status": {
      "previous": "DISCHARGED",
      "current": "AVAILABLE"
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

data object

The data property contains the full current state of the container, identical to the response from GET /v1/container/:containerId. Key fields include:

changes object

For this event, changes always contains the status field with previous and current values.

Common Use Cases

Workflow Shortcuts

• "When container becomes available" → container.status.updated where status = AVAILABLE
• "When container is outgated" → container.status.updated where status matches outgate statuses
• "When the status changes" → container.status.updated (no additional filter)