Subscribing to events

Webhook events allow you to receive real-time notifications when specific events occur in your tracked references. You can subscribe to various event types and direct these notifications to different endpoints based on your system architecture.

When creating a reference, you can specify which events you want to subscribe to and where you want to receive notifications for these events.

Specifying which events to receive

You can subscribe to specific event types by including a webhooks array in your reference creation payload. Each item in the array should specify the events you want to receive and the callback URL where you want to receive them.

{
  "carrier_scac": "CMDU",
  "container_id": "CONT1234567",
  "webhooks": [
    {
      "events": ["reference_update"],
      "callback_url": "http://example.com"
    },
    {
      "events": ["estimated_date_alerts"],
      "callback_url": "http://other.com"
    }
  ]
}

Available event types include:

reference_update - Receive notifications when your reference tracking data is updated
estimated_date_alerts - Receive notifications for changes in estimated arrival or departure dates

Specifying which event sources to receive

Events are triggered by milestones that come from various data sources. By default, when you subscribe to an event, you will receive notifications when the event is detected from any data source.

However, you can choose to specify which particular source (or sources) you want to receive events from by including the sources field in your webhook subscription:

{
  "carrier_scac": "CMDU",
  "container_id": "CONT1234567",
  "webhooks": [
    {
      "events": ["estimated_date_alerts"],
      "sources": ["carrier", "terminal"],
      "callback_url": "http://example.com"
    }
  ]
}

In this example, you'd only receive an estimated date alert if an estimated milestone with source: carrier or source: terminal has changed.

Available data sources include:

'*' - All data sources (default)
'carrier' - Carrier reported data
'rail' - Rail data
'ais' - AIS data
'terminal' - Terminal data
'vizion' - Vizion data

You can combine different events and sources to create finely tuned webhook subscriptions:

{
  "carrier_scac": "CMDU",
  "container_id": "CONT1234567",
  "webhooks": [
    {
      "events": ["reference_update"],
      "sources": ["carrier", "terminal"],
      "callback_url": "http://primary-system.example.com"
    },
    {
      "events": ["estimated_date_alerts"],
      "sources": ["carrier"],
      "callback_url": "http://alerts.example.com"
    },
    {
      "events": ["reference_update", "estimated_date_alerts"],
      "sources": ["*"],
      "callback_url": "http://audit.example.com"
    }
  ]
}

In this example:

The first endpoint receives reference updates only from carrier and terminal sources
The second endpoint receives estimated date alerts only from carrier sources
The third endpoint receives all event types from all data sources for comprehensive auditing

Registering multiple callbacks

You can register multiple callback URLs for the same event type or different event types. This allows you to:

Direct different event types to different endpoints
Send the same event type to multiple systems
Create specialized processing pipelines for specific event types

For example, you might want to send reference updates to your main system and estimated date alerts to a specialized alerting system:

{
  "carrier_scac": "CMDU",
  "container_id": "CONT1234567",
  "webhooks": [
    {
      "events": ["reference_update"],
      "callback_url": "http://main-system.example.com"
    },
    {
      "events": ["estimated_date_alerts"],
      "callback_url": "http://alerts.example.com"
    },
    {
      "events": ["reference_update", "estimated_date_alerts"],
      "callback_url": "http://audit.example.com"
    }
  ]
}

Callback payload structure

Webhook event payloads follow a consistent structure with an envelope format that helps you identify and process different event types. All webhook events include:

A payload_type field identifying the type of event
A payload object containing the event-specific data

This structure enables your systems to route and process different event types appropriately.

Example of a reference update event:

{
  "payload_type": "reference_update",
  "payload": {
    "id": "<ref_update_id>",
    "payload": {
      // Top level details
      "milestones": [
        // Milestones data
      ]
    }
  }
}

Example of an estimated date alert event:

{
  "payload_type": "estimated_date_alerts",
  "payload": {
    "changes": [
      {
        "type": "eta",
        "new_value": "y/m/d h:i:s",
        "old_value": "y/m/d/ h:i:s",
        "days_delta": 5,
        "percent_delta": 13,
        "milestone_id": "12345"
      },
      {
        "type": "etd",
        "new_value": "y/m/d h:i:s",
        "old_value": "y/m/d/ h:i:s",
        "days_delta": 7,
        "percent_delta": 27,
        "milestone_id": "23456"
      }
    ]
  }
}

Unsubscribing events

To stop receiving webhook events, you must unsubscribe the reference associated with the updates. If you don't unsubscribe and aren't using our auto-unsubscribe feature, Vizion will continue to send updates to the specified callback URLs.

Upgrading

Support for old callback payloads

To ensure backward compatibility with existing integrations, we continue to support the original webhook format alongside the new event-based structure.

If you want to continue receiving updates in the original format while also subscribing to new event types, you can include both the callback_url parameter and the webhooks array in your reference creation payload:

{
  "carrier_scac": "CMDU",
  "container_id": "CONT1234567",
  "callback_url": "http://example.com",
  "webhooks": [
    {
      "events": ["estimated_date_alerts"],
      "callback_url": "http://other.com"
    }
  ]
}

In this example:

The URL specified in callback_url will receive reference updates in the original format
The URL specified in the webhooks array will receive estimated date alerts in the new envelope format

This approach lets you gradually migrate your systems to the new webhook event structure without disrupting existing integrations.