Exception Alerts

Webhook events (see additional API reference documentation) also referred to as exception alerting, allow Vizion to notify your systems when tracking data changes for a reference you are monitoring. Instead of polling for updates, your system receives event notifications automatically at one or more callback URLs you control.

Step 1: Decide which events to receive

Before creating a reference, determine which types of events your system wants to receive. Currently supported event types:

• reference_update: Sent whenever tracking data for a reference changes
• estimated_date_alerts: Sent when estimated arrival or departure dates change beyond defined thresholds

Step 2: Create a reference with webhook subscriptions

Webhook subscriptions are defined when you create a reference using the Create a new reference endpoint. You do this by including a webhooks array in your reference creation payload. Each webhook array specifies 1) which events you want to receive and 2) where those events should be delivered.

{
  "carrier_scac": "MAEU",
  "container_id": "MAEU1234567",
  "webhooks": [
    {
      "events": ["reference_update"],
      "callback_url": "https://your-system.com/api/vizion-webhook"
    },
    {
      "events": ["estimated_date_alerts"],
      "callback_url": "https://alerts.your-system.com/webhook"
    }
  ]
}

Step 3: Filter Events by data source (optional)

By default, events are triggered regardless of where the underlying milestone data comes from. If you want finer control, you can restrict events to specific data sources. Supported sources include * (all sources, default), carrier, terminal, rail, ais, vizion.

{
  "webhooks": [
    {
      "events": ["estimated_date_alerts"],
      "sources": ["carrier", "terminal"],
      "callback_url": "https://alerts.com/api/vizion-webhook"
    }
  ]
}

Step 4: Examine JSON payloads

Webhook event payloads follow a consistent envelope structure, allowing your system to easily identify and process different event types. Each payload includes:

• payload_type: The event type (reference_update or estimated_date_alerts).
• payload: Object containing event-specific data.

Example: Reference update event

{
  "payload_type": "reference_update",
  "payload": {
    "id": "<ref_update_id>",
    "payload": {
      "milestones": [
        // milestone details here
      ]
    }
  }
}  

Example: Estimated date alert event

{
  "payload_type": "estimated_date_alerts",
  "payload": {
    "changes": [
      {
        "type": "eta",
        "new_value": "2026-01-25T12:00:00Z",
        "old_value": "2026-01-20T12:00:00Z",
        "days_delta": 5,
        "percent_delta": 13,
        "milestone_id": "12345"
      },
      {
        "type": "etd",
        "new_value": "2026-02-01T09:00:00Z",
        "old_value": "2026-01-25T09:00:00Z",
        "days_delta": 7,
        "percent_delta": 27,
        "milestone_id": "23456"
      }
    ]
  }
}

For full details on payload structure and subscription management, see the Webhook Events API reference documentation.