Menu
Home OceanIO Use cases Using Notifications

Using Notifications

The OceanIO platform offers access to 3 types of events (data, exceptions & notifications) within the Container Tracking Service. All event types can be accessed as push or pull. In the following article we will cover notifications.

Notification types

Notification overview and availability

The 6 types of notifications are listed in the following overview containing type, title, description and expected availability.

Notification_typeNotification_titleDescription of notificationAvailability
TRANSPORT_NOTIFICATIONCONTAINER_NOT_ASSIGNEDEarly Journey Notification
contains information about an early journey where there is not yet any containers assigned to the B/L or booking number.
Most Carriers
TRANSPORT_INFORMATIONTRANSPORT_COMPLETEDTransport Completed Notification indicates that the transport is completed in the OceanIO platform.All transports
TRANSPORT_SPLITCARRIER_BOOKKING_
REFERENCE_SPLIT

BILL_OF_LADING_
NUMBER_SPLIT
Split notification
informs that the booking is split into other bookings. “new_identifier” contains the new booking reference
only available for the Carrier Hapag
TRANSPORT_INFORMATIONCONTAINER_REMOVED
_FROM_TRANSPORT
Container removed notification indicates that the container is removed from the transport.all transports
CONTAINER_ROLL_OVERCONTAINER_ROLL_OVERRoll over notification indicates a vessel change.most carriers
SCHEDULE_CHANGEPORT_CALLS_REMOVED
PORT_CALLS_ADDED
PORT_CALL_TIME_DELAYED
PORT_CALLS_TIME_FORWARDED
PORT_CALLS_OCCURED
Schedule change notification (associated cost)
Schedule Change Notification requires a subscription on a Vessel IMO which is handled in the Schedule service.
For Schedule supported carriers

Working with notifications

Notifications are available via :

  • push, by creating a webhook with type=NOTIFICATION
  • pull, by calling GET /notifications

Early Journey Notification

Below is an example on an early journey notification.

{
 "correlation_id": "8eld8d34-5257-99jh-af0a-5af80e3c99d4",
 "notification_datetime": "2022-11-09T15:24:00+00:00",
 "notification_type": "TRANSPORT_NOTIFICATION",
 "notification_title": "CONTAINER_NOT_ASSIGNED",
 "data": {
   "correlation_id": "some_coorelation_id",
   "id": 1,
   "transport_id": "some_internal_id",
   "transport_type": "bill_of_lading_number",
   "identifier": "bol12345"
 }

Transport Completed Notification

When transports are completed the OceanIO generated an event. These TRANSPORT_COMPLETED events are available in the notification stream.

The example below shows an example of a TRANSPORT_COMPLETED event:

{
    "correlation_id": "bbd0d352-b82d-11ed-95fb-6e4851322151",
    "notification_datetime": "2023-03-01T12:36:48.241557+00:00",
    "notification_type": "TRANSPORT_INFORMATION",
    "notification_title": "TRANSPORT_COMPLETED",
    "data":
    {
        "correlation_id": "bbd0d0c8-b82d-11ed-95fb-6e4851322151",
        "id": 17650,
        "transport_id": "##transMRSU6142842(323f5a58-4be6-452a-a957-0fd5cfcdd626)",
        "identifier_type": "equipment_reference",
        "identifier": "MRSU6142842"
    }
}

A transport completed event for a equipment_reference, a carrier booking reference and a B/L will have the same notification type and title. Via identifier_type its possible to know which type of transport is completed.

Transport Split Notification

When a booking reference is split for the Carrier Hapag a notification is generated. – New transports are not automatically created.

The example below shows an example of a TRANSPORT_SPLIT event.

{
"correlation_id": "f6df424e-c278-11ed-9a8a-2284dcf3d66a",
"notification_datetime": "2023-03-14T15:00:31.204294+00:00",
"notification_type": "TRANSPORT_SPLIT",
"notification_title": "CARRIER_BOOKING_REFERENCE_SPLIT",
"data": 
   {
    "correlation_id": "f6df401e-c278-11ed-9a8a-2284dcf3d66a",
    "id": 18465,
    "transport_id": "##trans(c1633054-6a11-4f7b-9758-d4f3e3298576)",
    "identifier_type": "carrier_booking_reference",
    "identifier": "69543071",
    "new_identifiers": [
    "21120828",
    "85805632",
    "60548078"
   ]
   }
}


Container Removed Notification

Below is an example on a container removed notification

{
     "correlation_id": "00b44d88-40cc-11ee-a5ec-a28dd5b86e60",
     "notification_datetime": "2023-08-22T09:12:22.438543+00:00",
     "notification_type": "TRANSPORT_INFORMATION",
     "data": {
       "correlation_id": "00b44b76-40cc-11ee-a5ec-a28dd5b86e60",
       "id": 87064,
       "transport_id": "##trans(a49a8bcb-5003-4065-aff9-92df0376bd8b)",
       "identifier_type": "equipment_reference",
       "identifier": "MSMU1274234"
     },
     "notification_title": "CONTAINER_REMOVED_FROM_TRANSPORT"
}

Rollover Notification

Below is an example on a rollover notification

{
  "correlation_id": "89b62120-731b-11ee-92b2-ba297c40ccdd",
  "notification_datetime": "2023-10-25T09:47:40.678973+00:00",
  "notification_type": "CONTAINER_ROLL_OVER",
  "notification_title": "CONTAINER_ROLL_OVER",
  "data": {
    "correlation_id": "89b61f04-731b-11ee-92b2-ba297c40ccdd",
    "id": 38215,
    "transport_id": "-8dee25fa-bf45-473c-b374-24e37b9ae9a8",
    "equipment_reference": "KMTU9344920",
    "original_vessel_name": "SOME_VESSEL",
    "original_vessel_imo_number": 7777777,
    "new_vessel_name": "STAR VOYAGER",
    "new_vessel_imo_number": 9754795,
    "un_location_code": "JPSZK"
  }
}

Schedule Change Notification

Below is an example on a Schedule Change Notification

{

    "correlation_id": "4ae6865e-3a2e-11ee-8bbb-aa725bd96b16",
    "notification_datetime": "2023-08-13T23:08:19.458994+00:00",
    "notification_type": "SCHEDULE_CHANGE",
    "data": {
      "correlation_id": "4ae6856e-3a2e-11ee-8bbb-aa725bd96b16",
      "vessel_operator_carrier_code": "MAEU",
      "vessel_imo_number": 1234567,
      "service_schedule": {
        "correlation_id": "4ae6847e-3a2e-11ee-8bbb-aa725bd96b16",
        "schedule_id": 2650916,
        "carrier_service_code": "D6G",
        "carrier_service_name": null,
        "vessel_imo_number": 1234567,
        "vessel_name": "CAPRICORN 59",
        "port_calls": [
           {
            "port_call_status_code": null,
            "import_voyage_number": "676G",
            "export_voyage_number": "677B",
            "un_location_code": "IDBUR",
            "location_name": "BATAM ISLAND",
            "country": "ID",
            "timezone": "Asia/Makassar",
            "port_terminal_location": "BATAM ISLAND TERMINAL",
            "facility_type_code": null,
            "facility_smdg_code": null,
            "other_facility": null,
            "delay_reason_code": null,
            "change_remark": null,
            "transport_event_type_code": "ARRI",
            "event_classifier_code": "ACT",
            "event_datetime": "2023-08-12T04:00:00+00:00",
            "cy_cut_off": null,
            "fcl_cut_off": null,
            "vgm_cut_off": null,
            "dg_cut_off": null,
            "si_cut_off": null
          },
           {
            "port_call_status_code": null,
            "import_voyage_number": "676G",
            "export_voyage_number": "677B",
            "un_location_code": "IDBUR",
            "location_name": "BATAM ISLAND",
            "country": "ID",
            "timezone": "Asia/Makassar",
            "port_terminal_location": "BATAM ISLAND TERMINAL",
             "facility_type_code": null,
            "facility_smdg_code": null,
            "other_facility": null,
            "delay_reason_code": null,
            "change_remark": null,
            "transport_event_type_code": "DEPA",
             "event_classifier_code": "ACT",
            "event_datetime": "2023-08-12T15:00:00+00:00",
            "cy_cut_off": null,
            "fcl_cut_off": null,
            "vgm_cut_off": "2023-08-12T16:00:00+00:00",
            "dg_cut_off": null,
            "si_cut_off": null
           }
         ],
        "source_name": "MAERSK"
       }
     },
    "notification_title": "PORT_CALLS_OCCURRED"
   }
Updated on 26 February, 2024