Webhook Events

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_event_alerts"],
      "callback_url": "http://other.com"
    }
  ]
}

Available event types include:

• * - Subscribe to all event types listed below. Useful when you want a single endpoint to see the full lifecycle of a reference.
• reference_update - Receive notifications when your reference tracking data is updated
• estimated_event_alerts - Receive notifications for changes in estimated arrival or departure dates

Receivable payload types

When subscribed to *, your endpoint may receive any of the following payload_type values. The two granular subscription options above (reference_update, estimated_event_alerts) deliver only their corresponding payload types.

You can also retrieve the same events historically via the reference events endpoint.

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_event_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_event_alerts"],
      "sources": ["carrier"],
      "callback_url": "http://alerts.example.com"
    },
    {
      "events": ["reference_update", "estimated_event_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_event_alerts"],
      "callback_url": "http://alerts.example.com"
    },
    {
      "events": ["reference_update", "estimated_event_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_event_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"
      }
    ]
  }
}

Lifecycle event payloads share an envelope. Each payload includes an event_id (the lifecycle event's unique id, useful for de-duplication) alongside event-specific fields. Examples:

{
  "payload_type": "reference_created",
  "payload": {
    "event_id": "0190e1c4-7b8a-7c9d-9e1f-3a2b1c4d5e6f",
    "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
    "organization_id": "b18c3f2e-7d6a-4f81-8b2c-9e0d1a2c3b4f",
    "identifier_type": "container_id",
    "identifier_value": "CONT1234567",
    "carrier_scac": "CMDU"
  }
}

{
  "payload_type": "reference_deactivated",
  "payload": {
    "event_id": "0190e1c5-8c9b-7c9d-9e1f-3a2b1c4d5e6f",
    "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
    "organization_id": "b18c3f2e-7d6a-4f81-8b2c-9e0d1a2c3b4f",
    "auto_unsubscribed": true,
    "deactivate_reason": "too_long_without_updates"
  }
}

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_event_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.